maat-retrospect

Retrospect: adopt Ma'at in an existing repository

Follow this procedure when maat init has run in an established repository and the scaffolded documentation does not yet reflect the actual codebase. You (the agent) supply the judgment; the maat CLI supplies deterministic facts; the developer supplies the intent. Work in a pair-programming session — this procedure is interactive by design.

Ground rules

• Never invent intent. Code tells you what; only the developer can confirm why. When context cannot be recovered, write "unknown — inferred from code" rather than a plausible fabrication.
• Never overwrite hand-written content without showing the developer the change first. Files maat init skipped are pre-existing and owned by the team.
• Decisions derived after the fact are archaeology, not records. Give them status: retrospective, and only document decisions that still constrain the codebase today. Do not backfill superseded history.
• Small steps: propose, confirm, write, re-check — one document at a time.

Procedure

1. Inventory the gaps deterministically.
   • Read the create/skip output of maat init (re-run it if needed — it is idempotent and never overwrites). skip lines are pre-existing files to reconcile; create lines are scaffolds with placeholder content to fill.
   • Run maat check and collect every finding. This is your work list.
2. Explore the codebase before asking anything. Entry points, build and test commands, CI configuration, directory layout, recurring conventions, external dependencies. Form hypotheses to verify in the interview, not open questions the code already answers.
3. Interview the developer. Cover at least:
   • What does this project do, in one paragraph? (project summary)
   • What must an agent never do here? What always? (update protocol, conventions)
   • Which parts of the architecture are deliberate and constraining, and why? (candidate retrospective ADRs)
   • Which existing docs/READMEs are trustworthy, which are stale?
4. Reconcile AGENTS.md. If it pre-existed, merge Ma'at's expectations (project overview, update protocol, links into docs/) into the existing text — preserve the team's voice and rules. If it was scaffolded, replace the placeholders with interview results.
5. Fill the scaffolded docs under docs/ (architecture overview, guides, reference). Set honest front-matter: status: draft for anything unverified, status: current only for reviewed content. Wire up related_code so staleness tracking starts working.
6. Derive retrospective ADRs in docs/decisions/ from the interview — one per living constraint, using the ADR template, with status: retrospective.
7. Close the loop. Run maat sync, then maat check; fix findings until green. Show the developer the final diff.
8. Ratchet the severities. Where .maat.yml's check section was loosened for adoption, propose tightening (warn → error) now that the corresponding gaps are closed.