document

skills/groundwork/commands/document.md skills/groundwork/templates/

init is for repos with nothing. document is for repos with something stale. It delta-merges, preserving the why.

When to use it

  • Stack changed: new test framework, package manager, or build tool.
  • CLAUDE.md exists but the agent keeps producing code that does not match the repo.
  • Mature repo adopting Groundwork for the first time.
  • After an audit with "stale context" findings.

What it produces

  • Existing files extended, not overwritten.
  • Stale sections moved to a ## Deprecated block with date and reason.
  • Chat summary that names what changed: added, deprecated, kept.

How it works

  1. Detect what exists. Globs every known context-file location. Notes last-modified date and approximate accuracy.
  2. Read the repo deeply. Last 50 commits and a sample of recent files. Checks whether existing conventions still match the code.
  3. Ask three questions. Which detected rules are still correct? Which new patterns should be written in? Anything to mark deprecated?
  4. Delta-merge. Correct sections kept verbatim. Drifted sections: new content added with a date, old content moved to a deprecated block with the reason.
  5. Anchored-rule sweep. Walks the Style section. Each rule must name a verb plus a specific technology, command, or pattern. Vague rules ("write robust error handling") get surfaced as anchor / drop / keep choices; the command never silently rewrites them.
  6. Reconcile across harnesses. If CLAUDE.md and AGENTS.md disagree, surface the diff. Never pick a winner silently.
  7. Verify. Same fail-loudly behaviour as init.