跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

adr-writer

Author an Architecture Decision Record that captures a non-obvious technical choice — its context, the decision, the consequences, the rejected alternatives, and the reversibility cost. Use whenever a non-trivial dependency is picked, a framework is chosen, a one-way door is opened, two specialists disagree and the orchestrator must pick, or anyone in a future session would ask "why did we do this?" An ADR exists so the answer is on disk, not in someone's head. Its lifecycle status lives in frontmatter in the schema's one vocabulary (proposed, accepted, open, deferred, hotfix, rejected, superseded, closed); superseding is a new ADR plus a status flip on the old — never an edit of its body.

llopresto87 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add llopresto87/Cypress --skill adr-writer

技能说明


name: adr-writer description: Author an Architecture Decision Record that captures a non-obvious technical choice — its context, the decision, the consequences, the rejected alternatives, and the reversibility cost. Use whenever a non-trivial dependency is picked, a framework is chosen, a one-way door is opened, two specialists disagree and the orchestrator must pick, or anyone in a future session would ask "why did we do this?" An ADR exists so the answer is on disk, not in someone's head. Its lifecycle status lives in frontmatter in the schema's one vocabulary (proposed, accepted, open, deferred, hotfix, rejected, superseded, closed); superseding is a new ADR plus a status flip on the old — never an edit of its body. id: skill.adr-writer tier: 2 kind: skill origin: seed title: adr-writer — record non-obvious technical choices as short, superseded-never-edited ADRs owns:

  • adr-writer.method
  • adr-writer.reversibility
  • adr-writer.numbering requires: peers:
  • skill.grill-planner
  • agent.architect
  • skill.humanizer load_when:
  • "write an ADR"
  • "record an architecture decision"
  • "why did we choose this dependency or design"
  • "supersede an existing decision record, mark an ADR superseded"
  • "which ADRs are still open, hotfix, or deferred"
  • "ADR status: proposed, accepted, superseded_by"
  • "opening a one-way door decision"
  • "accepted risk, declined fix, or an owner-declared no-go area" artifacts:
  • templates/adr.template.md
  • decisions/README.md prevents: Choices whose reasoning exists only in the session that made them, so a later reader sees what was decided but not what was rejected or what reversing it would cost. est_tokens: 2760

adr-writer

ADRs (Architecture Decision Records) live in docs/graph/decisions/ and record every non-obvious technical choice. Each is a short, recorded answer to "why did we pick this?"; a design doc is a different artifact.

This skill encodes the discipline of writing them well.

When to apply this skill

  • A new dependency is being committed to (the wiki page handles the what; the ADR handles the why).
  • A framework, language, or platform is being chosen.
  • A one-way door is being opened (data model, public API contract, vendor lock-in).
  • A boundary between two services or modules is being drawn.
  • Two specialists disagreed and the orchestrator picked an option.
  • A bug post-mortem revealed an implicit decision that should have been explicit.
  • A T2 contained-lane change made a real choice among options and owes its why-record (tiers.contained-lane). Write the short form: Context, Decision, Consequences, Reversibility, the sections that carry the why. Skip Alternatives when none were weighed, and say so in one line. A contained change whose why needs every section was misclassified: hand it back for T3.
  • Anyone asks "why did we do it this way?" and the answer isn't in an existing ADR.

ADR numbering and status

ADRs are numbered monotonically: adr-NNNN-short-slug.md. Find the next free number in docs/graph/decisions/ and in the index, because a number can be taken without a file. Each number names one decision for good, because citations outlive files.

A number allocated to a decision that is owed but not yet written (a spec reserves it, or the owner has not ruled yet) gets an index row marked reserved or owed, naming who owes the body. The index row is the whole reservation, because a stub ADR file is fiction that satisfies a linter. The reservation holds even when the decision is abandoned. Where a program keeps more than one ADR series (one per repository, say), a citation names the series as well as the number, so two ADRs with the same number cannot be confused.

Status lives in frontmatter, in the schema's lifecycle vocabulary (docs/graph/_schema.md §"Lifecycle status" is the home; read it for the meanings): status: proposed | accepted | open | deferred | hotfix | rejected | superseded | closed, always with status_date, plus the companion the value requires: owner while open | hotfix | deferred, reopen_when when deferred, status_evidence when closed, superseded_by when superseded. The body's ## Status section is a pointer to the frontmatter; a body value that disagrees is a lint failure (python3 docs/graph/status-register.py --root docs/graph), the drift the register exists to catch. An ADR is born proposed and becomes accepted when the owner ratifies it (the grill.md §6 row); the base values apply as the schema defines them: a "do nothing now" decision parked behind a named trigger is deferred with reopen_when, a choice taken under pressure that owes a proper decision is hotfix with an owner.

To replace a decision, write a new ADR with a new number and status: accepted, and set the old ADR's frontmatter to status: superseded + superseded_by: ADR-NNNN + a fresh status_date. That flip is the only edit a ratified ADR ever receives; its body is never rewritten (the append-only exception in holistic-editing). To see what is still owed: python3 docs/graph/status-register.py --by-kind adr --open --hotfix (add --deferred for parked decisions). The register is the query surface; the index at docs/graph/decisions/README.md is the human table.

The template (4 sections that matter most)

Use docs/graph/templates/adr.template.md. Its frontmatter is the status home (above); the four body sections that earn their keep:

Context

What is the situation that forces a decision? Include the constraint that makes "do nothing" not viable. Cross-link to grill.md and the relevant spec.

Bad: "We need a database."

Good: "Spec SPEC-0003 requires submissions to persist across restarts. Grill.md §4 caps p95 latency at 200ms and cost at $X/month. The current implementation uses an in-memory map, which loses state on restart. We need to choose a persistent store."

When the owner states how an external arrangement work

阅读完整来源 ↗