architecture-decision-records

Files (2)

• SKILL.md
• SKILL.md.lock

SKILL.md (first lines)

<!-- bodyRef: skills/sources/architecture-decision-records.md -->

<!-- Generated by `harness skills bootstrap`. Edit to tune; re-run to regenerate. -->
<!-- Static skills point at live docs by design — do not hardwire version-pinned API here. -->

Use this skill when making or recording a load-bearing technical decision.

## Concepts (timeless)
- An ADR captures one decision: its Context, the Decision, the Consequences (positive AND negative), and the Alternatives considered.
- Record the decision when it's made, while the context is fresh — not retroactively.
- ADRs are immutable once accepted; a later decision that reverses one is a NEW ADR that supersedes it.
- Keep them short and concrete; link to the code/PR that implements the decision.
- Record the "why not" — the alternatives rejected are often more valuable than the choice.

## Pull current docs first
Use the project's existing ADR location/format if one exists:
- ADR templates: https://adr.github.io/
- Common conventions: `docs/adr/NNNN-title.md` (MADR / Nygard templates).

## Checklist
- [ ] One decision per record; Context / Decision / Consequences / Alternatives present
- [ ] Both positive and negative consequences stated
- [ ] Status set (proposed/accepted/superseded) + date
- [ ] Superseding decisions reference the ADR they replace
- [ ] Linked to the implementing PR/commit

## Gotchas

_Highest-signal section. Seed empty; grow it from real failures this skill
hits — `harness skills propose` suggests entries here from drift evidence._

- _none observed yet_

From ichiorca/shipsignal, Apache-2.0.

More from ichiorca/shipsignal