Docs Reflect

---
name: docs-reflect
description: "Collect DOC: notes from session, generalize, and propose repo documentation (.claude/rules/, docs/)."
user-invocable: true
argument-hint: "[optional focus area]"
allowed-tools:
  - Bash(node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" *)
---

# /docs-reflect — Session knowledge → repo documentation

Collect DOC: notes accumulated since the last review, generalize them into rules, and propose documentation for the repository.

---

## Step 1: Collect findings

Two sources: DOC: notes since the last review, and recurring feedback from memory.

### 1a: DOC: notes

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" docs
```

Lists DOC: notes after the last `DOCS_REVIEWED` marker (Step 6 writes it). `docs --all` lists every note, reviewed or not.

### 1b: Recurring feedback patterns

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" recurring
```

This scans `feedback/` files for clusters — similar corrections that appeared 2+ times across sessions. Recurring patterns are strong candidates for promotion to `.claude/rules/`.

### Combine

If both sources are empty — tell user "No documentation findings." and stop.

If recurring patterns found (3+ occurrences) — these are project conventions, not personal preferences. Treat them as DOC automatically:
- Save as DOC note: `node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" note "DOC: <domain> — <generalized rule from recurring feedback>"`
- Highlight to user: "This feedback appeared N times — promoting to project rule."

Patterns with 2 occurrences — mention as candidates but don't auto-promote.

---

## Step 2: Generalize

For each DOC: note, extract a generalized rule.

Bad (too specific):
> "The PaymentService bug was on line 42 in processRefund()"

Good (pattern):
> "Refund operations must check transaction state before mutating — stale state causes double-refunds"

Bad (class-level):
> "UserService.getProfile() returns null when user is not found"

Good (convention):
> "Services return null for missing entities instead of throwing — callers must handle null"

If a note can't be generalized — skip it.

---

## Step 3: Detect documentation structure and route

### 3a: Detect existing structure

```bash
ls .claude/rules/ 2>/dev/null
cat CLAUDE.md 2>/dev/null | head -50
ls docs/ 2>/dev/null
```

Check memory for saved preference:
```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" search "docs_target"
```

### 3b: Choose target

If no saved preference and no `.claude/rules/` directory — ask:

```
Where should project rules go?
  1. .claude/rules/ (Claude Code loads these per-directory)
  2. docs/
  3. CLAUDE.md (single file, always loaded — use sparingly)
  4. Other — specify path

Choice? (default: 1)
```

Save preference:
```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" note "CONFIG: docs_target=<chosen path>"
```

### 3c: Route by domain

Route using the chosen target directory (default: `.claude/rules/`):

| Domain | Target |
|--------|--------|
| testing | `<target>/testing.md` |
| api | `<target>/api.md` |
| architecture | `<target>/architecture.md` |
| state | `<target>/state.md` |
| workflow | `<target>/workflow.md` |
| Other domain | `<target>/<domain>.md` |
| Truly universal (rare) | `CLAUDE.md` |

If a matching file exists — add to it. If not — create one.

---

## Step 4: Propose changes

```
## Docs-reflect: <date>

Found N DOC: notes, grouped into M domains:

### <target>/testing.md
- <rule 1>
- <rule 2>

### <target>/api.md
- <rule 3>

### Skipped
- <notes too specific to generalize>

Apply? (all / pick numbers / skip)
```

Wait for user confirmation.

---

## Step 5: Apply

For each approved rule:

1. Read target file (or create with header)
2. Add rule to appropriate section
3. Format:

For rule files (`.claude/rules/`, `docs/`, or custom target):
```markdown
## <Section>

- <Rule>
```

---

## Step 6: Close the review

**MANDATORY** once the user has answered Step 4 — applied, picked or skipped. Skipped notes count as reviewed:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" docs --mark-reviewed
```

Don't mark if the run was limited to a focus area or the user stopped before answering — those notes stay for the next run.

---

## Rules

- **Generalize or skip.** Can't state it as a reusable rule → don't add it.
- **No class/method API docs.** Those belong in code comments.
- **No ticket/branch references.** Docs should not mention specific tasks.
- **Right file matters.** The main value is routing to the correct `.claude/rules/` file.
- **Deduplicate.** Read existing docs before adding.
- **User confirms first.** Never write without showing what will be added.
- **Respect existing structure.** Add to existing files/sections. Don't reorganize.
- **Less is more.** 2 good rules is a great outcome. 0 is fine too.