---
name: docs-reflect
description: Extract decisions and corrections from session history, propose .claude/rules/
user-invocable: true
argument-hint: "[--current | --history N]"
---

# /docs-reflect — Session knowledge → repo documentation

Extract decisions, corrections, and insights from session transcripts. Propose `.claude/rules/` entries.

No plugins required. Works with bash/python scripts for transcript parsing.

## Step 1: Gather raw material

Two modes:

### A) Current session (default, or `--current`)

Ask the model to review the current conversation and list:
- Corrections the user made ("don't do X", "always do Y")
- Decisions with reasoning ("chose X because Y")
- Surprising constraints or platform behaviors
- Patterns that should become rules

### B) History (`--history N` — last N sessions)

Run the extraction script:

```bash
python3 ~/.claude/scripts/extract-findings.py --last N
```

The script outputs structured findings from `.jsonl` transcripts.

## Step 2: Classify findings

Group by domain:

```
Found 7 findings:

testing (3):
  - "integration tests must hit real DB, not mocks"
  - "always run tsc --noEmit before committing"
  - "mock external APIs, not internal services"

architecture (2):
  - "webhook handlers must be idempotent"
  - "use repository pattern for DB access"

process (2):
  - "PR must have test plan section"
  - "don't amend published commits"
```

## Step 3: Check existing rules

```bash
ls .claude/rules/ 2>/dev/null
cat .claude/rules/*.md 2>/dev/null
```

Show what already exists. **Do NOT duplicate existing rules.**

## Step 4: Ask where to put rules

**MUST ask the user where documentation lives in this project before proposing locations.**

```
Where do you keep project rules/documentation?
  1. .claude/rules/  (Claude Code rules)
  2. docs/            (project docs)
  3. CLAUDE.md        (project instructions)
  4. Other — specify path

Choose:
```

**Wait for response. Do NOT assume `.claude/rules/` by default.**

## Step 5: Propose

**MUST show all proposed rules with target locations and wait for user confirmation before writing.**

```
Proposed rules → {chosen target}:

1. → {target}/testing.md (new file)
   "Integration tests must hit real DB. Mock external APIs, not internal."

2. → {target}/testing.md (append)
   "Run tsc --noEmit before committing."

3. → {target}/architecture.md (new file)
   "Webhook handlers must be idempotent."

Write? (all / 1,3 / skip)
```

## Step 6: Write

After confirmation, create/update files in the chosen target.

Each rule file:
```markdown
# {Domain}

- {Rule 1}
- {Rule 2}
```

Keep rules concise — one line per rule, no essays.

## Rules

- Never write without user confirmation
- Never duplicate rules that already exist in .claude/rules/ or CLAUDE.md
- Generalize — not "fixed auth.ts bug" but "validate JWT expiry before refresh"
- One domain per file in .claude/rules/
- If --history used, script must exist at ~/.claude/scripts/extract-findings.py