Files

Dobromir Popov 2e0dd3732a docs: update issue-tracker.md with full .scratch → docs/ lifecycle

Documents the complete feature lifecycle: grilling → to-prd → to-issues
into .scratch/, then /close-feature graduates to docs/. Covers conventions
for both active and closed features, and the proactive close-feature trigger.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-07-01 14:46:26 +03:00

2.1 KiB

Raw Blame History

Issue tracker: Local Markdown

Lifecycle

Active feature work lives in .scratch/<feature-slug>/. When a feature is complete, /close-feature graduates it into docs/. This keeps in-progress work isolated from the permanent record.

/grilling → /to-prd → /to-issues → .scratch/<slug>/
                                         ↓ all Status: done
                                    /close-feature
                                         ↓
                                      docs/

During a feature (in .scratch/)

.scratch/<slug>/PRD.md — narrative PRD
.scratch/<slug>/prd.json — machine-readable story list (used by ralph)
.scratch/<slug>/issues/<NN>-<slug>.md — user stories, numbered from 01
Triage state is a Status: line near the top of each issue (see triage-labels.md)
Comments and conversation history append under a ## Comments heading

After close (in docs/)

docs/PRD.md — narrative PRD (appended under a feature heading)
docs/prd.json — merged story list
docs/issues/<NN>-<slug>.md — renumbered from next available slot
docs/adr/<NNNN>-<slug>.md — any ADRs from the feature, renumbered

Closing a feature

Run /close-feature <slug> when all issues have Status: done. The skill will:

Verify all issues are done (stops if any are incomplete)
Show what will move and ask for confirmation
git mv everything into docs/ with correct numbering
Merge prd.json user stories into docs/prd.json
Delete .scratch/<slug>/ and commit

The agent should also proactively offer to run /close-feature when it notices all issues in a .scratch/<slug>/ are done.

When a skill says "publish to the issue tracker"

Create a new file under .scratch/<feature-slug>/issues/ following the numbering convention. Create the directory if it doesn't exist.

When a skill says "fetch the relevant ticket"

Read the file at the referenced path. The user will normally pass the path or issue number directly. Check both docs/issues/ (closed features) and .scratch/*/issues/ (active features).

2.1 KiB Raw Blame History