---
name: close-feature
description: Graduate a completed feature from .scratch/<slug>/ into the permanent docs/ structure. Run when all issues in the feature are done, or when the agent notices a feature looks complete. Always confirm with the user before moving files.
---

# Close Feature

Merge a completed `.scratch/<slug>/` feature into the permanent `docs/` structure and delete the scratch directory.

## When to run

Run this skill when:
- The user explicitly calls `/close-feature <slug>`
- You notice during any task that ALL issues in a `.scratch/<slug>/issues/` directory have `Status: done` — surface this proactively and offer to close ("It looks like <slug> is fully done. Want me to graduate it to docs/?")

Always confirm before moving any files.

## Process

### 1. Identify the slug

If called with an argument (`/close-feature <slug>`), use that. Otherwise list all `.scratch/` directories and ask the user which one to close.

### 2. Verify all issues are done

Read every file in `.scratch/<slug>/issues/`. Check for a `Status:` line.

If any issue does NOT have `Status: done`, list the incomplete ones and stop — ask the user whether to mark them wontfix or wait.

### 3. Show the user what will move

Present a summary:
- N issues → `docs/issues/` (renumbered from next available)
- PRD.md → `docs/PRD.md` (or merged if one already exists)
- prd.json → `docs/prd.json` (merged into existing user stories array)
- Any ADRs written during the feature → `docs/adr/` (renumbered from next available)
- `.scratch/<slug>/` deleted

Ask: "Proceed?" before touching anything.

### 4. Move issues

Find the highest existing number in `docs/issues/`. Issues from `.scratch/<slug>/issues/` take the next slots in dependency order (lowest numbered first).

Use `git mv` for each file so history is preserved:
```
git mv .scratch/<slug>/issues/01-foo.md docs/issues/<next>-foo.md
```

### 5. Merge PRD

If `docs/PRD.md` does not exist: `git mv .scratch/<slug>/PRD.md docs/PRD.md`

If `docs/PRD.md` already exists: append the feature's Problem Statement and Solution sections under a `## <Feature Name>` heading. Do not overwrite the existing file.

### 6. Merge prd.json

If `docs/prd.json` does not exist: `git mv .scratch/<slug>/prd.json docs/prd.json`

If `docs/prd.json` already exists: merge the `userStories` array from the scratch prd.json into the main one, assigning new sequential ids to avoid collisions. Update all merged stories to `"status": "done"`.

### 7. Move ADRs

If any `.md` files exist directly in `.scratch/<slug>/` (not in `issues/`) that look like ADRs (contain `## Status` and `## Decision`), move them to `docs/adr/` renumbered from the next available slot.

### 8. Delete scratch directory

```
git rm -r .scratch/<slug>/
```

If `.scratch/` is now empty, remove it too (it has no meaning without sub-features).

### 9. Commit

```
git add docs/
git commit -m "docs: close feature <slug> — graduate to docs/"
```

### 10. Update ralph default (if needed)

If `scripts/ralph_progress.py` exists and its `DEFAULT_PRD` still points at `.scratch/<slug>/prd.json`, update it to `docs/prd.json`.

## Machine setup reference

Skills are stored in `.agents/skills/` and symlinked into `.claude/skills/`. Both directories are git-tracked so cloning the repo gives you all skills automatically.

**On a new machine (Linux/Mac):**
```bash
git clone <repo>
# Skills work immediately — .claude/skills/ symlinks resolve automatically.
# .claude/settings.local.json is machine-local (gitignored).
# Recreate it if you need custom permission allowlists.
```

**On Windows:**
```bash
git clone -c core.symlinks=true <repo>
# Requires Developer Mode or admin rights for symlink creation.
# If symlinks didn't resolve, run: scripts/link-skills.sh (or re-run /setup-matt-pocock-skills)
```

**Codex:** reads `AGENTS.md` at the repo root — already tracked, no setup needed.

**Hermes / other local LLM tools:** add their context files to the repo root or `docs/` and commit. Point the tool at that file in its config.

**To add a new skill to the repo:**
```bash
mkdir .agents/skills/<name>
# write .agents/skills/<name>/SKILL.md
ln -s ../../.agents/skills/<name> .claude/skills/<name>
git add .agents/skills/<name> .claude/skills/<name>
git commit -m "skill: add <name>"
```