doc-expert

Scan code and history for architecturally significant decisions that lack ADRs. Produces BACKFILL-ADR candidates and open questions only; never drafts without human confirmation.

Audit documentation and ADR coverage against the four-question test and ADR canon. Finds stale/cluttered docs plus architecture decisions visible only in code/history, surfacing BACKFILL-ADR candidates without drafting. Produces a KEEP / MERGE / REWRITE / DELETE / MOVE / BACKFILL-ADR action list — does not delete anything without sign-off.

Lint a Markdown document — two-pass review (syntax must-fix, then style should-fix) per-finding with architect approval. Cites a rule and source layer for every finding. Does not bulk-rewrite.

Audit a pre-existing or legacy ADR line-by-line. Quotes offending lines verbatim, names the rule broken, proposes shorter rewrites, requires per-line approval. Use for ADRs that did NOT go through the /adr-new + adr-drafting flow.

Run the zero-hallucination pre-flight Q&A before writing an ADR. Confirms domain, components, relationships, related ADRs, and decision-makers one fact at a time. Produces a discovery brief and an open-questions register. Use BEFORE drafting if context is fuzzy.

Documentation, Markdown style, and Architecture Decision Record (ADR) expert. PROACTIVELY activate for: (1) writing or recording ADRs and architectural decisions, (2) missing ADRs, missing decision records, implicit decisions in code, architecture/code archaeology, undocumented architecture, inherited or legacy repos, stale architecture docs, or suspicious ADR gaps, (3) migrations, vendor removals, dependency replacements, platform rewrites, or subsystem retirements, (4) creating docs under docs/, architecture/, adr/, decisions/, rfcs/, or design/, (5) ADR discovery, critique, audits, supersession, deprecation, or revisit workflows, (6) deciding ADR vs RFC vs runbook vs code comment, (7) doc drift, dead docs, duplicate decisions, governance, or BACKFILL-ADR candidates, (8) canonical-C4 LikeC4 diagrams, (9) Markdown/README linting. Provides: ADR lifecycle, discovery briefs, audits, templates, doc placement diagnostics, missing-ADR scans, BACKFILL-ADR surfacing, and Markdown linting.

This skill should be used to retroactively record an architectural decision that was made in the past but never written up as an ADR — typically surfaced by a doc audit or by a user realising a long-ago shipped change should have been documented. PROACTIVELY activate on "backfill ADR", "retroactive ADR", "post-hoc ADR", "reconstruct an ADR from history", "write up a past decision", "we never documented this decision", "decision was made but no ADR exists", "we decided years ago", "back when", "before my time", or "the audit surfaced a backfill candidate." Tense rule: `adr-drafting` claims "we decided / we're deciding"; `adr-backfill` claims "we decided years ago / back when / before my time / never wrote it down." Refuses when reconstruction confidence is `low` -- routes to `open-questions.md`. Requires evidence in two independent locations and a verbatim honesty clause in the record. Provides: backfill ADR template, confidence rubric, evidence corroboration, honesty-clause boilerplate.

This skill should be used to audit an existing or legacy ADR, especially one imported, LLM-generated, stale, or never self-critiqued. PROACTIVELY activate on "review this ADR", "critique this ADR", "audit our decision log", "is this ADR any good?", "fix this old ADR", "rewrite this legacy ADR", "ADR cleanup", "ADR quality sweep", "tighten this ADR", "score these ADRs", or "this ADR is too long." Provides: line-by-line ADR critique, filler/hedging/drift detection, and per-line approval workflow.

This skill should be used before drafting an ADR when context, components, relationships, deciders, or prior decisions are unclear. PROACTIVELY activate on "I want to write an ADR for X", "gather context for a decision", "discovery for an ADR", "ADR intake", "ADR pre-flight", "prep work before an ADR", "what's the current architecture?", or "set up a decision log." Provides: zero-hallucination Q&A, human-confirmed discovery brief, open-questions register, and five required confirmations before drafting.

This skill should be used when a decision is ready to become an ADR and the user wants co-thinking rather than template filler. PROACTIVELY activate on "draft the ADR", "write up the decision", "co-think this ADR", "challenge my reasoning", "ADR for X", "MADR for X", "Y-statement for X", "we decided to use X", "co-draft", "ADR drafting", or "scripted push-back." Provides: seven-phase ADR drafting, one-question turns, failure-mode pressure test, and self-critique against the ADR-is-NOT checklist.

This skill should be used to create or update a C4 architecture diagram alongside an ADR, especially in LikeC4. PROACTIVELY activate on "add a C4 diagram", "create a context diagram", "container view", "LikeC4 model", "draw the architecture", "diagram this decision", "architecture diagram for the ADR", "visualize the components", "C4 view", or "Simon Brown C4." Provides: canonical-C4 Context and Container views from confirmed elements, relationship descriptions, and strict refusal of non-canonical diagram types.