groove-work-doc

Outcome

Acceptance Criteria

• Overview: What this component/concept is and what problem it solves
• Key Files: The most important files, with a one-line role for each
• How It Works: Step-by-step explanation of the main flow or logic
• Gotchas: Non-obvious constraints, edge cases, known sharp edges

Constraints

• Sanitize topic for use as filename — strip path separators, special characters, and traversal patterns (

  ../

  )
• Read

  memory:

  and

  specs:

  from

  .groove/index.md

  ; resolve docs directory as

  <specs>/../docs/

  if

  specs:

  key is present, otherwise

  <memory>/docs/

• Ensure the resolved docs directory exists (create if missing)
• Research the codebase thoroughly before writing (use Explore agent) — docs should reference actual file paths, not generic descriptions
• Interview user if scope is ambiguous: "What's the audience — a new contributor, a future agent, or both?"
• Write doc in isolated context (use general-purpose agent)
• Verify all four required sections exist before completing
• Keep each section concise — this is a reference doc, not a tutorial

Quality Signals

• Key Files lists actual paths found in the codebase
• How It Works traces a real execution path (e.g. "user runs X → Y reads config → Z writes file")
• Gotchas surface things that are not obvious from reading the code
• Doc does not duplicate what a spec already says — link to the spec if one exists