Deep ADR

deep-adr

A family of four Claude skills that co-think Architecture Decision Records with the architect — challenging, pushing back, and refusing to write an ADR until the reasoning holds up. Designed to fix the failure mode of AI-generated ADRs stuffed with filler, hedging, and implementation detail.

These are not template fillers. They behave like a senior architect in a review.

Quick start

npx skills add janmohammadi/deep-adr --all

Then invoke any skill from your agent: /adr-discovery, /draft-adr, /adr-critique, /c4-model. For GitHub Copilot or per-skill installs, see Install below.

Pairs with ADR Explorer — once deep-adr has helped you produce a corpus of ADRs on disk, ADR Explorer visualizes the graph (supersedes / amends / relates-to), scores corpus health, surfaces stale or orphan decisions, and can distill bloat. Available as npx adr-explorer or as a VS Code extension.

The four skills

Skill	When to use
adr-discovery	Before drafting, especially on unfamiliar systems. Gathers project context through back-and-forth Q&A with zero hallucination — every fact confirmed by the human before it counts. Captures the measurable facts needed for an ADR's Architecture Contract and logs unknowns to docs/architecture/open-questions.md with where-to-look / who-to-ask guidance.
draft-adr	When the architect has a decision to make. Co-thinks through Understand → Context → Options → Decide → Draft → Self-Critique → Save. Pushes back, drafts an ADL-aware Architecture Contract when the decision creates enforceable assertions, and refuses to write if context is thin or reasoning is weak. 7-phase flow.
adr-critique	Auditing an existing or legacy ADR that wasn't drafted via draft-adr. Line-level flags against the ADR-is-NOT checklist with per-line rewrite approval. Catches missing-why, weak Architecture Contracts, inconsistency, and LikeC4 drift.
c4-model	Generating a canonical-C4 LikeC4 model reflected from confirmed architectural elements and embedded ADL assertions. Context + Container views only, optionally Deployment. Refuses Component views, custom element kinds, dynamic views, and other LikeC4 features that deviate from Simon Brown C4 conventions.

Typical workflow

What makes these different

• Zero hallucination — adr-discovery never states a fact about the project the human hasn't confirmed. Every finding from code is presented as "I found X in [file]. Is this accurate?" and waits for a yes/no. Business domain, component purpose, and relationships are always asked, never inferred.
• Push-back, not capitulation — draft-adr is scripted to challenge weak reasoning, name the strongest counter-argument, and require the architect to articulate 2–3 failure modes before accepting a decision. Forbidden affirmations: "Great question", "Solid approach", "Good thinking".
• Architecture Contract, not vague compliance — ADRs can embed a compact adl block where each assertion carries its own check metadata. The ADR keeps the human why; the Architecture Contract records the objective facts that must stay true.
• Self-critique before save — draft-adr runs the ADR-IS-NOT checklist on its own draft output, quotes violating lines, rewrites them, and presents the revised draft for approval. You never see its first draft.
• Canonical-C4 by construction — c4-model locks LikeC4's flexible DSL to the Simon Brown C4 Model style and reflects embedded ADL assertions into the model. No Component views, no custom kinds, no dynamic views. In-skill lint runs before likec4 validate.
• Open-questions mechanism — when the architect doesn't know something, the skills don't fabricate. They help scope the answer (where to look, who to ask) and log to docs/architecture/open-questions.md — a path deliberately outside the four directories typically scanned by ADR parsers.

Architecture Contract

deep-adr uses an Architecture Contract section instead of a vague Compliance section. The contract keeps the enforceable assertion and its check metadata in one place:

• ADL assertions — the objective architecture facts that must hold.
• Inline checks — how each assertion is checked, including trigger, owner, and severity.