Sync Architecture

Sync Architecture (post-implementation)

Keep docs/architecture/* and the domain docs live by detecting, from a completed task's diff, what the change introduced that the docs haven't caught up with — then proposing the exact doc deltas. It runs in the same post-implementation phase as ../review-implementation/SKILL.md, but asks a different question:

review-implementation asks "is this diff good code?" — this skill asks "does this diff introduce anything the docs don't yet know about?" The first is code debt; this is documentation drift.

It is the automated detection half of the manual /update-architecture workflow. Where /update-architecture is a heavy, human-invoked pass (and also runs the improve-codebase-architecture deepening loop), this skill is a lightweight detector that runs automatically after each task so the docs stop silently drifting. It reuses /update-architecture's routing table — it does not invent its own.

Silence is the default output. A task that introduced nothing doc-worthy (a bug fix, styling, a trivial CRUD following existing patterns) produces no deltas — that is the normal case. A finding survives only if the docs are genuinely now wrong or incomplete. Never invent doc churn to look thorough.

ALWAYS check .ab-method/structure/index.yaml FIRST for where the architecture and domain docs live — paths are user-configurable. Sweep only what this task changed — the cohesive diff across its missions (git diff for the commit range) plus its progress-tracker.md mission summaries. This is not a whole-repo doc audit.

Look for it under the project root (the current working directory) first — a project's own copy is how it customises its paths, so it always wins. Only if the project has none (AB Method installed as a plugin rather than with npx ab-method), read the bundled default: ../../../.ab-method/structure/index.yaml relative to this SKILL.md. Either way, every path the index names is relative to the project root, never to the folder the bundled file lives in.

Process

1. Gather diff + context

• The changed files and their git diff for the task's commit range.
• The task's progress-tracker.md Mission Summaries — the per-mission Files / Built / Integrates with bullets already enumerate most of what's new.
• The current architecture + domain docs, so the detector proposes only what's genuinely missing (skip files that don't exist): docs/architecture/tech-stack.md, frontend-patterns.md, backend-patterns.md, UBIQUITOUS_LANGUAGE.md, CONTEXT.md, docs/adr/.

2. Spin up ONE read-only detector subagent

Spawn a single subagent — architecture-sync — with the diff, the mission summaries, the current docs, and the task's unresolved-questions.md if it has one. It is read-only: it returns a routed findings list (often empty) and edits nothing. Isolating it keeps the doc analysis out of the orchestrator's context. On Codex (spawn_agent is one level deep) spawn it at the orchestrator's own level; on Claude it may nest. One detector is enough — the whole point is a single sweep of the change.

Its brief — detect only what the docs don't already capture, routed with /update-architecture's table:

For each finding return: What (the concrete thing the diff introduced, citing the file/mission), Doc (the exact target file + section), Proposed delta (the append-only line or short section to add), Class (see Step 3).

Example: "New endpoint POST /charges (src/api/charges.ts, mission 2) — not in tech-stack.md Entry Points. Proposed delta: add POST /charges — create a charge (auth: bearer) under Entry Points. Class: safe-add."

Never document a black box as established practice. If the diff contains TODO(UQ-n) seams recorded in the task's unresolved-questions.md, the placeholder behind them is provisional by construction — do not write it into tech-stack.md as a constraint, into a patterns doc as "the way we do this", or into UBIQUITOUS_LANGUAGE.md as a term. A parked question is also never an ADR candidate: an ADR records a decision that was made, and this one wasn't. The real thing the docs may be missing is what the change built around the black box (the new endpoint, the new dependency, the seam's existence) — route that normally, and describe the placeholder only as what it is, e.g. "currency is fixed to USD pending UQ-1". When the question is later answered via /extend-task, the resulting decision syncs like any other.

Out of scope — do not raise: code-quality issues (that's review-implementation), whole-repo deepening opportunities (that's /improve-codebase-architecture), or rewrites of existing prose. With nothing the docs are missing, return exactly: Docs in sync — no architecture updates needed.