The ADR job, front to back — where your agent hits the wall

Your agent will write you a clean architecture decision record. Point it at a choice — Postgres over Mongo, a modular monolith over microservices — and it picks a template, fills in the context, weighs the options, spells out the consequences, and argues back when your reasoning is thin. Read the output and it looks finished.

It isn't. An ADR isn't done when it's written. It's a claim about the system that has to stay true while the code keeps moving. Decide, draft, and even govern a single record, and the tooling is right there with you. Ask it to keep a whole log of decisions honest against a drifting codebase — to tell you what you decided about auth and what quietly replaced it, or whether last year's call actually worked out — and an agent working from these skills starts to run out of road.

The front of the job is well covered. The back is where you hit the wall. Here's the map.

What you can hand your agent

Deciding the architecture in the first place

Before there's a decision to record, there's a decision to make. architecture-selection turns that into a scored exercise: it builds evaluation criteria from team size, domain complexity, scaling needs and ops maturity, forces at least two candidate patterns onto the table, and names the anti-patterns that should scare you off one — distributed monolith, premature optimization, resume-driven development. architecture-patterns works the same lens as a catalog, pairing each pattern with the failure mode that kills it. If you want the whole architect role rather than just the pattern pick, senior-architect runs requirements to design to record — quantified non-functional requirements, a weighted decision matrix, a modular-monolith default it makes you argue your way out of. All three end where the next stage begins: an ADR.

Finding the decisions already in the code, or the chat

Half the decisions worth recording were made months ago and never written down. adr-discovery is the disciplined way in: it globs the repo for signals but refuses to assert anything, presenting every finding as a question — "I see pg and ioredis in package.json, is Postgres your primary store?" — and nothing enters the brief until you confirm it. For decisions buried in a working session instead of the filesystem, adr-decision-extraction mines a transcript for choice language and trade-off debates, tagging each find high, medium or low confidence, and write-adr wraps that into an end-to-end run: extract, show you the list, confirm, then write each record with a pre-allocated number so parallel writers can't collide. architecture-decision-records watches from the other direction — it flags decision moments as they surface during a session and offers to capture them, rather than letting them evaporate into a Slack thread.

Drafting the decision itself

This is the busiest region, and it splits cleanly by how much rigor you want. At the demanding end, adr-drafting refuses to hand you a first draft at all — it works one question per turn through options, forces you to name failure modes before it will advance, delivers a scripted counter-argument to your leading choice, then self-critiques the whole thing against an "ADR is not" checklist and only shows you the revision. decision-analysis is the pre-commit stress test: a premortem imagining each option failing, a backcast working back from success, and a Go / No-Go / Conditional-Go verdict fed into the record.

If you want the decision to be checkable later, adr-author is the sharp one — it grades each decision HIGH, MEDIUM or LOW on enforceability and pushes you to embed concrete, extractable constraints (file paths, version bounds, config values) that a linter or CI rule could verify. Note the shape of that promise, though: it writes decisions a tool can check, not the tool that checks them.

For the everyday case — record it, number it, keep it — architecture-decision-records is the comprehensive workhorse, carrying MADR, lightweight, Y-statement, deprecation and RFC templates plus a review checklist and the lifecycle. And when a decision has to trace back to upstream requirements, doc-adr is the heavyweight: ten numbered sections, mandatory two-to-three alternatives with cost and fit, and a readiness score the record must clear before it's allowed to move to Accepted.

Governing a single record over its life

Once a record exists, keeping it clean is its own job. adr-critique audits a legacy or imported ADR line by line, quoting the offending text verbatim, naming the rule it breaks, catching "missing-why" reasoning that leans on "best practice," and refusing to silently edit an Accepted record — it recommends supersession instead of rewriting history. When you write the record that replaces an old one, adr-author handles supersession properly: it flips both files' status atomically and its lineage allocator is the single writer of the decision counter, so numbers never collide. The catch is that this bookkeeping only fires while you're authoring the successor — it's not a standing "reconcile the whole log" button you can press on its own. And on the remediation side, doc-adr-fixer reads an audit report and applies the targeted fixes, closing the audit-then-fix loop so a flagged record can converge to passing.

Backfilling decisions already shipped

For the decision that shipped years ago with no record, adr-backfill is built for exactly the honesty trap: it demands evidence in two independent locations, refuses to draft if the "why" would have to be invented, and stamps a mandatory clause on the record so no future reader mistakes a reconstruction for a contemporaneous note. At adoption scale, migrate sweeps a brownfield repo for historical decisions and backfills them under per-step authorization, without rewriting history or manufacturing a rejected alternative to satisfy a template.

The design specialties an ADR sits on top of

Many architecture decisions are really decisions inside a specialty, and the deep skills are here. microservices-patterns leads with the monolith-versus-microservices decision itself before it touches decomposition, sagas or circuit breakers. event-driven-architecture goes deep on brokers, the transactional outbox, idempotency and schema evolution. database-schema-design covers modeling, the SQL-versus-document choice, indexing and safe migrations. And c4-model draws canonical Context and Container diagrams alongside the ADR, then runs a drift check that compares the component names in your ADR text against the diagram model and flags the mismatches.

What can't your agent finish here?

Three things, and they're the ones that matter most once the log is more than a few files old. Read this as guidance about where to keep a human in the loop, not a knock on any one skill.

Nothing checks that the code still matches the decision

This is the big one. An ADR is a promise about the system, and the skills here never go back to the running code to see if the promise held. The tools that come close all audit the wrong surface. propagate-design-change re-scans your ADRs when a design document changes — but it compares them to that document, not to the code. architecture-audit inspects the codebase hard for shallow modules and coupling, but it never reads your decision records at all. c4-model catches names that drift between a diagram and an ADR, not behavior that drifts in the implementation. And the enforceability skill embeds constraints a CI check could enforce without ever running that check. So a decision the code has quietly outgrown keeps reading as Accepted, indefinitely. Closing that gap — pointing an audit at the live code and asking "does this still comply?" — is on you.

A folder of decisions is not a queryable decision graph

The capture skills call the log "searchable," and technically it is: they write index tables and populate frontmatter links between related records. But those get rendered by external viewer tools — none of these skills is the thing you call to ask, across the whole corpus, "what did we decide about auth, and what superseded it?" The pipeline behind doc-adr-autopilot will append a row to an index when it generates a new record — a table it writes to, not one it answers questions from. adr-critique reads a target ADR plus its immediate neighbors, never the full set. Even adr-drafting is honest that the cross-links to related records are yours to update by hand in a separate pass. Past a handful of decisions, retrieval is you and grep.

Status tracks the decision's life, never whether it worked

Proposed, accepted, superseded, deprecated — that lifecycle is administrative. It records what happened to the document, not what happened to the bet. Nothing here revisits an accepted decision after time has passed to check whether its predicted consequences actually came true and feeds that verdict back into status. adr-drafting lets you set a review-by date; decision-analysis runs its premortem before you commit. Both point at the right question. Neither does the post-hoc pass that answers it. Whether the decision was a good one stays a human judgment, made outside these tools.

The bottom line

The decision-writing core is genuinely strong. Deciding the pattern, discovering what's undocumented, drafting under real pressure, governing one record, backfilling the past — hand any of those to your agent and it will do serious work. What it can't do yet is keep the record honest against a codebase that won't hold still: catching drift, querying the graph, and grading outcomes are still yours to carry. Pick the skills for the front of the job, and staff the back of it yourself.