From 2e0dd3732abc1a4263f203a824187705cba7429b Mon Sep 17 00:00:00 2001
From: Dobromir Popov <dobromir.popov@gmail.com>
Date: Wed, 1 Jul 2026 14:46:26 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20update=20issue-tracker.md=20with=20full?=
 =?UTF-8?q?=20.scratch=20=E2=86=92=20docs/=20lifecycle?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 docs/agents/issue-tracker.md | 46 +++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 9 deletions(-)

diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
index 41e6d2b..2671f98 100644
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -1,19 +1,47 @@
 # Issue tracker: Local Markdown
 
-Issues and PRDs for this project live as markdown files under `docs/`.
+## Lifecycle
 
-## Conventions
+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.
 
-- The PRD is `docs/PRD.md` (narrative) and `docs/prd.json` (machine-readable story list used by ralph)
-- Implementation issues (user stories) are `docs/issues/<NN>-<slug>.md`, numbered from `01`
-- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
-- ADRs (architecture decisions) are `docs/adr/<NNNN>-<slug>.md`, numbered from `0001`
-- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+```
+/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 `docs/issues/` following the numbering convention.
+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 the issue number directly.
+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).