Skip to content

docs: add repository gotchas to copilot-instructions #421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
spboyer wants to merge 1 commit into
base: main
Choose a base branch
from
+57 −0
Open

docs: add repository gotchas to copilot-instructions #421

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,60 @@ If you make a decision that affects other team members, write it to:
.squad/decisions/inbox/copilot-{brief-slug}.md
```
The Scribe will merge it into the shared decisions file.

## Repository Gotchas (learned from past sessions)

These come up repeatedly across sessions. Handle them proactively.

### 1. First `go build/test/lint` in a fresh worktree needs a `web/dist` stub

The Go binary embeds the dashboard via `//go:embed all:dist` (`web/embed.go`). In a fresh
worktree the built assets don't exist, so any Go command fails until you scaffold them:

```bash
mkdir -p web/dist && [ -f web/dist/index.html ] || echo '<html></html>' > web/dist/index.html
```

Run this **once** at the start of any session before `go build`, `go test`, or `golangci-lint run`.

### 2. Never restage a regenerated `web/dist/index.html`

`web/dist/assets/*` is gitignored but `web/dist/index.html` **is tracked**. Running
`cd web && npm run build` rewrites `index.html` with new hashed asset refs, which then
shows up as an unrelated diff. Before `git add`:

```bash
git diff -- web/dist/index.html # if only hash refs changed, revert it
git checkout -- web/dist/index.html
```

Only commit `web/dist/index.html` changes when you intentionally shipped new dashboard code.

### 3. Standard verify chain: format → test → lint

`golangci-lint` fails on unformatted code, so always run `gofmt` first to avoid a
retry loop:

```bash
gofmt -w ./... && go test ./... && golangci-lint run
```
Comment on lines +97 to +99

For the docs site and dashboard, add:

```bash
cd site && npm run build
cd ../web && npm run build && npm run lint
```

### 4. Clean up scratch dirs before committing

Agent tooling can leave `.impeccable/` in the worktree, and Node builds create
`web/node_modules/` and `site/node_modules/`. None of these should be staged. Before
`git add`:

```bash
rm -rf .impeccable web/node_modules site/node_modules
git status --short # verify only intended files remain
```

`git add -A` from the repo root is risky — prefer explicit paths.
Loading