Update Docs (any stack) — where does this go?
Tracking + this repo's ids/labels:
docs/project-tracking/GITHUB-PROJECTS.md. Companions: /start-feature · /finish-feature.
The one rule
New WORK is a GitHub issue on this repo's Project — never a markdown tracker file. Files are for
design intent (specs, decisions, VISION) and append-only history (changelog.d/). Capture, then
return to the current branch.
Decision tree
| When this happens | It becomes | Then you |
|---|---|---|
| Bug surfaces mid-work | Bug issue — link to current issue | keep going |
| Roadmap enhancement / idea | Feature issue (sub-issue if under an epic) | keep going |
| Multi-stream initiative | Epic + sub-issues | start one sub-issue |
| Small chore | Task issue | keep going |
| Design decision | docs/DECISIONS.md — reference from issue |
note it |
| Non-trivial design | docs/specs/ or docs/design/ — link from issue |
write the doc |
| Current work finished | PR Closes #<issue> + changelog.d/ fragment |
merge → Done |
Creating an issue
url=$(gh issue create --repo <owner>/<repo> \
--title "<title>" --body "<context; if mid-work: 'Found while working #<n>'>" \
--label type:bug --label priority:high --label area:<slice>)
gh project item-add <n> --owner <owner> --url "$url"
Owner, project number, and area:* labels: docs/project-tracking/GITHUB-PROJECTS.md.
Files that still go under docs/
| Velocity | Files |
|---|---|
| Slow-moving | docs/specs/*.md, docs/design/*.md, docs/VISION.md |
| Append-only | changelog.d/YYYY-MM-DD-<slug>.md, DECISIONS.md |
Common mistakes
- Markdown file for new work instead of an issue
- Skipping
item-addor labels - Letting a surfaced bug derail the current branch
- Editing
CHANGELOG.mdon a feature branch - Putting long design only in the issue body (use a spec)
- Adding feature logic to the shared kernel, or coupling across product/feature boundaries