# 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:
1. Verify all issues are done (stops if any are incomplete)
2. Show what will move and ask for confirmation
3. `git mv` everything into `docs/` with correct numbering
4. Merge prd.json user stories into `docs/prd.json`
5. 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).