cad (docs/adr/000X-*.md) hand-rolls a solid ADR template that's never been codified as a reusable skill: frontmatter (adr/title/status/date/deciders/supersedes) + Status/Context/Decision/Consequences/Validation sections. Codify it generically here.
Fold in architecture/preserving-productive-tensions (from obra/superpowers-skills, not yet vendored): don't force premature resolution on genuinely context-dependent tradeoffs — document as Option A/B + preservation strategy + resolution trigger. cad already does this informally (ADR-0001's "Known refinements, deliberately not built yet" section — 3-class sovereignty deferred, taskqueue reuse deferred) — this formalizes it as the discipline for the Consequences section.
Part of moving cad's requirements/architecture workflow off gsd-* onto bespoke skills (research verdict: gsd-*/spec-kit/BMAD/Kiro are all upstream-only spec authoring, no runtime audit — orthogonal to this gap, not a replacement for it).
cad (`docs/adr/000X-*.md`) hand-rolls a solid ADR template that's never been codified as a reusable skill: frontmatter (adr/title/status/date/deciders/supersedes) + Status/Context/Decision/Consequences/Validation sections. Codify it generically here.
Fold in `architecture/preserving-productive-tensions` (from obra/superpowers-skills, not yet vendored): don't force premature resolution on genuinely context-dependent tradeoffs — document as Option A/B + preservation strategy + resolution trigger. cad already does this informally (ADR-0001's "Known refinements, deliberately not built yet" section — 3-class sovereignty deferred, taskqueue reuse deferred) — this formalizes it as the discipline for the Consequences section.
Part of moving cad's requirements/architecture workflow off gsd-* onto bespoke skills (research verdict: gsd-*/spec-kit/BMAD/Kiro are all upstream-only spec authoring, no runtime audit — orthogonal to this gap, not a replacement for it).
Shipped in 2cb6b54. Both halves: cad's template codified, and architecture/preserving-productive-tensions folded in as a first-class section rather than a footnote.
The RED run changed what this skill is for
An unaided agent, given a genuinely undecidable transport choice, wrote a good ADR. It invented a "Cost of reversal" section, wrote firing conditions rather than "revisit as needed", and reframed the unanswerable question into an answerable one:
rather than asking which option is better (unanswerable), I asked which option's correctness depends on the unsettled variables.
So the reasoning was never the gap. What it could not guess was the house format — it invented a bullet header instead of the frontmatter that makes the corpus greppable, and wrote no Validation section at all. That is the honest case for this skill: not teaching judgement the model has, but pinning the conventions it cannot infer, and codifying the good moves so a weaker model makes them too.
The GREEN run found eleven problems
Four worth reading:
The Overview contradicted the Escalation section in its own first sentence — "An ADR is not documentation of a decision. It is the decision" against "decides nothing". Escalation was right.
The escalation clause trapped every ADR an agent will ever write. The deciders are never the agent, so proposed is mandatory — and the skill separately called a lingering proposed a failure mode. The run noted its own draft was "now sitting in exactly that trap". Now: a proposed ADR with a named decider is waiting on a person and gets chased; one without is waiting on nobody. Naming that person is the deliverable.
No filename or path convention — called "the biggest hole in the skill", in a skill whose stated thesis is greppability. Fixed, with the cross-repo caveat that adr: 0002 is ambiguous between cad and infra and needs qualifying in supersedes.
One rule would have produced a worse ADR. "Pick the option whose correctness does not depend on the unknown" assumes such an option exists:
It frequently doesn't — a tension is productive precisely because both options are hostage to the same unknown. [...] it forces the author to manufacture a reason that one of them is, which is the skill's own anti-pattern wearing better prose. Worse, the manufactured rationale is more damaging than an honest arbitrary pick, because it reads as reasoned and won't be re-examined.
There is now a fallback ladder — cheaper to reverse, lower switching cost, already built — and an instruction to say that is why you picked it.
Also fixed: deciders had no valid value while proposed; the body ## Status duplicated frontmatter with no precedence rule; the tension template silently dropped the "address the strongest case against" requirement the plain format demands; the preservation strategy — the actual technical content — got a single angle bracket while the easy parts got full templates; and lineage/grill-me sat in Cross-References at the bottom when they are pre-steps that change what goes in the document.
One thing the run did that I did not ask for and would not have caught: it flagged that its own output path and ADR number were assumptions, because it had been told to read only the SKILL.md. That is the behaviour the Escalation section is trying to produce.
Shipped in `2cb6b54`. Both halves: cad's template codified, and `architecture/preserving-productive-tensions` folded in as a first-class section rather than a footnote.
## The RED run changed what this skill is for
An unaided agent, given a genuinely undecidable transport choice, wrote a good ADR. It invented a "Cost of reversal" section, wrote firing conditions rather than "revisit as needed", and reframed the unanswerable question into an answerable one:
> rather than asking which option is better (unanswerable), I asked which option's correctness *depends on* the unsettled variables.
So the reasoning was never the gap. What it could not guess was the **house format** — it invented a bullet header instead of the frontmatter that makes the corpus greppable, and wrote no Validation section at all. That is the honest case for this skill: not teaching judgement the model has, but pinning the conventions it cannot infer, and codifying the good moves so a weaker model makes them too.
## The GREEN run found eleven problems
Four worth reading:
**The Overview contradicted the Escalation section in its own first sentence** — *"An ADR is not documentation of a decision. It is the decision"* against *"decides nothing"*. Escalation was right.
**The escalation clause trapped every ADR an agent will ever write.** The deciders are never the agent, so `proposed` is mandatory — and the skill separately called a lingering `proposed` a failure mode. The run noted its own draft was *"now sitting in exactly that trap"*. Now: a `proposed` ADR with a named decider is waiting on a person and gets chased; one without is waiting on nobody. Naming that person is the deliverable.
**No filename or path convention** — called *"the biggest hole in the skill"*, in a skill whose stated thesis is greppability. Fixed, with the cross-repo caveat that `adr: 0002` is ambiguous between `cad` and `infra` and needs qualifying in `supersedes`.
**One rule would have produced a worse ADR.** "Pick the option whose correctness does not depend on the unknown" assumes such an option exists:
> It frequently doesn't — a tension is *productive* precisely because both options are hostage to the same unknown. [...] it forces the author to manufacture a reason that one of them is, which is the skill's own anti-pattern wearing better prose. Worse, the manufactured rationale is *more* damaging than an honest arbitrary pick, because it reads as reasoned and won't be re-examined.
There is now a fallback ladder — cheaper to reverse, lower switching cost, already built — and an instruction to say that is why you picked it.
Also fixed: `deciders` had no valid value while proposed; the body `## Status` duplicated frontmatter with no precedence rule; the tension template silently dropped the "address the strongest case against" requirement the plain format demands; the preservation strategy — the actual technical content — got a single angle bracket while the easy parts got full templates; and `lineage`/`grill-me` sat in Cross-References at the bottom when they are pre-steps that change what goes in the document.
One thing the run did that I did not ask for and would not have caught: it flagged that its own output path and ADR number were assumptions, because it had been told to read only the SKILL.md. That is the behaviour the Escalation section is trying to produce.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
cad (
docs/adr/000X-*.md) hand-rolls a solid ADR template that's never been codified as a reusable skill: frontmatter (adr/title/status/date/deciders/supersedes) + Status/Context/Decision/Consequences/Validation sections. Codify it generically here.Fold in
architecture/preserving-productive-tensions(from obra/superpowers-skills, not yet vendored): don't force premature resolution on genuinely context-dependent tradeoffs — document as Option A/B + preservation strategy + resolution trigger. cad already does this informally (ADR-0001's "Known refinements, deliberately not built yet" section — 3-class sovereignty deferred, taskqueue reuse deferred) — this formalizes it as the discipline for the Consequences section.Part of moving cad's requirements/architecture workflow off gsd-* onto bespoke skills (research verdict: gsd-*/spec-kit/BMAD/Kiro are all upstream-only spec authoring, no runtime audit — orthogonal to this gap, not a replacement for it).
Shipped in
2cb6b54. Both halves: cad's template codified, andarchitecture/preserving-productive-tensionsfolded in as a first-class section rather than a footnote.The RED run changed what this skill is for
An unaided agent, given a genuinely undecidable transport choice, wrote a good ADR. It invented a "Cost of reversal" section, wrote firing conditions rather than "revisit as needed", and reframed the unanswerable question into an answerable one:
So the reasoning was never the gap. What it could not guess was the house format — it invented a bullet header instead of the frontmatter that makes the corpus greppable, and wrote no Validation section at all. That is the honest case for this skill: not teaching judgement the model has, but pinning the conventions it cannot infer, and codifying the good moves so a weaker model makes them too.
The GREEN run found eleven problems
Four worth reading:
The Overview contradicted the Escalation section in its own first sentence — "An ADR is not documentation of a decision. It is the decision" against "decides nothing". Escalation was right.
The escalation clause trapped every ADR an agent will ever write. The deciders are never the agent, so
proposedis mandatory — and the skill separately called a lingeringproposeda failure mode. The run noted its own draft was "now sitting in exactly that trap". Now: aproposedADR with a named decider is waiting on a person and gets chased; one without is waiting on nobody. Naming that person is the deliverable.No filename or path convention — called "the biggest hole in the skill", in a skill whose stated thesis is greppability. Fixed, with the cross-repo caveat that
adr: 0002is ambiguous betweencadandinfraand needs qualifying insupersedes.One rule would have produced a worse ADR. "Pick the option whose correctness does not depend on the unknown" assumes such an option exists:
There is now a fallback ladder — cheaper to reverse, lower switching cost, already built — and an instruction to say that is why you picked it.
Also fixed:
decidershad no valid value while proposed; the body## Statusduplicated frontmatter with no precedence rule; the tension template silently dropped the "address the strongest case against" requirement the plain format demands; the preservation strategy — the actual technical content — got a single angle bracket while the easy parts got full templates; andlineage/grill-mesat in Cross-References at the bottom when they are pre-steps that change what goes in the document.One thing the run did that I did not ask for and would not have caught: it flagged that its own output path and ADR number were assumptions, because it had been told to read only the SKILL.md. That is the behaviour the Escalation section is trying to produce.