doc

name	doc
description	Mid-work documentation — persist decisions, findings, and reasoning to the right file before context fills up. Figures out WHAT to write and WHERE to put it.
user-invocable	true
argument-hint	[what to document, e.g. 'design decision on evaluator trigger', 'PJE case study reframing']
allowed-tools	Read, Write, Edit, Grep, Glob, Bash

Doc — Mid-Work Documentation Persistence

Capture what just happened — decisions, findings, design choices, reasoning — and write it to the correct file on disk before context compression loses it.

Design principle: /doc is the complement of /cycle. Where /cycle is post-hoc ("we're done, update everything"), /doc is mid-work ("something worth remembering just happened — save it now"). Together they ensure nothing falls through the gap between discovery and documentation.

When to trigger:

• A design decision was just made or resolved
• A finding emerged from analysis or discussion
• An architectural choice was debated and settled
• Context usage is above 50% and substantive work hasn't been persisted
• The agent notices it's holding reasoning that only exists in conversation

When NOT to trigger:

• Trivial exchanges (greetings, clarifications, small corrections)
• Work that /cycle will handle at session end
• Information already on disk (check before writing)

Phase 1: Identify What to Document

Parse $ARGUMENTS and recent conversation context to determine:

1. What happened — the decision, finding, or reasoning to persist
2. Type classification:

 Type              Examples                           Typical destination
──────────────────────────────────────────────────────────────────────────
 Design decision   "evaluator uses tiered activation"  MEMORY.md, CLAUDE.md,
                                                       or architecture doc

 Finding           "skills can't natively chain"        MEMORY.md or
                                                        research doc

 Reasoning chain   "why PJE is a case study not a       Snapshot file or
                    sub-agent"                           architecture doc

 Convention        "always use LaTeX for complex docs"   MEMORY.md

 Architecture      "four-layer agent system"              Architecture doc

 Status update     "PSQ analysis complete, moving to     MEMORY.md
                    architecture"

3. Novelty check — read the target file first. If the information is already captured, report "already documented at [location]" and stop. Don't duplicate.

Phase 2: Determine Where to Write

The project has a document hierarchy. Each type of information has a natural home. Choose the most specific applicable location:

Decision tree

Is it a stable convention or policy?
  → Yes → MEMORY.md (Communication Conventions or Working Principles section)

Is it about the psychology agent architecture?
  → Yes → Does an architecture doc exist?
    → Yes → Write there
    → No  → Create one at docs/architecture.md (markdown, not LaTeX —
             architecture is living documentation, not a publication)

Is it a one-time finding or reasoning chain worth preserving?
  → Yes → Is it significant enough to warrant a snapshot?
    → Yes → Create docs/snapshots/snapshot-YYYYMMDD-HHMM-[slug].md
    → No  → MEMORY.md (Active Thread section, briefly)

Is it a status update on where we are in the work?
  → Yes → MEMORY.md (Active Thread section — overwrite, don't append)

Is it project-specific to a sub-project (e.g., safety-quotient)?
  → Yes → Write to that sub-project's documentation, not the parent

File locations

 File                                    What goes here
──────────────────────────────────────────────────────────────────
 MEMORY.md                               Active thread, conventions,
 (~/.claude/projects/.../memory/)         design decisions, status

 docs/architecture.md                    System architecture, sub-agent
 (project root)                          protocol, evaluator design

 docs/snapshots/snapshot-*.md            Significant reasoning chains,
 (project root)                          paradigm shifts, decision records

 Sub-project CLAUDE.md / MEMORY.md       Sub-project-specific conventions
 (e.g., safety-quotient/)               and state

Phase 3: Write

Writing rules

1. Read the target file first. Understand its current structure before editing.

2. Match the existing style. If MEMORY.md uses terse bullet points, write terse bullet points. If an architecture doc uses APA-style prose, write APA-style prose.

3. Overwrite status, append findings. The "Active Thread" section of MEMORY.md should reflect current state (overwrite). New design decisions or conventions should be added to the appropriate section.

4. Date-stamp snapshots. Snapshot filenames include the date and a slug: snapshot-20260301-1430-evaluator-design.md

5. Keep MEMORY.md under 200 lines. If an addition would push it over, move detailed content to a linked file and summarize in MEMORY.md.

6. Cross-reference. If the documented item relates to content in another file, add a brief cross-reference: "See also: docs/architecture.md §3"

Phase 4: Confirm

Report to the user:

Documented: [1-line summary of what was written]
Location:   [file path]
Action:     [created / updated / already documented]

If context usage is high (>60%), suggest: "Context is at N% — consider running /cycle soon to do a full documentation pass."

If the work session is producing findings faster than they're being documented, suggest: "Multiple undocumented decisions in context — want me to do a batch /doc pass?"

Phase 5: Chain (optional)

If the documentation pass reveals that a full /cycle is warranted (e.g., multiple files are now stale, or the session is ending), suggest running /cycle. Do not auto-invoke — let the user decide.