groove-work-doc

name	groove-work-doc
description	Create a 'how does X work' documentation file for a codebase component or concept. Use $ARGUMENTS as the doc topic if provided.
license	MIT
allowed-tools	Read Write Edit Glob Grep Bash(git:*) AskUserQuestion
metadata	{"author":"andreadellacorte"}

groove-work-doc

Use $ARGUMENTS as the doc topic if provided.

Outcome

A structured documentation file explaining how a component, concept, or pattern works — for future agents and humans picking up the codebase.

Acceptance Criteria

Doc file contains:

• 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 (../)
• Docs directory is always .groove/memory/docs/
• Ensure the 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