diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index aa276e24..1f282d3c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -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 '' > 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 +``` + +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.