Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
bump: minor
---

### Added

- `record-decision` Step 3: a citation sweep lists, by `file:line`, every tracked line citing the retired record's identifier or path, and proposes pointing each at the new record or dropping it, applied in the same change behind the same yes. It runs for every `adr_retirement` value and for a partial reversal, where only citations of the reversed part change.
- `record-decision audit`: each retire candidate lists the lines citing it; the audit stays read-only.
- `record-decision` Step 4: after a record is written, it offers one pointer comment at the code the decision governs, citing the record in the repository's own form, and writes it only after a yes.
7 changes: 5 additions & 2 deletions plugins/architecture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,8 +188,11 @@ considered options, optional consequences) beside one or two other shapes, and
writes nothing at all until you pick one: this plugin never imposes a convention
on a repository that has none. When a new decision reverses an existing record,
it retires the old one after your yes: deleted (the default), marked superseded,
or archived, per `adr_retirement`. `audit` lists records the code or a later
decision no longer backs, and changes nothing. A team can set its own template,
or archived, per `adr_retirement`, and in the same change repoints or drops
each line that cites the old record, listed by `file:line`. After writing a
record it offers one pointer comment at the code the decision governs, added
only on your yes. `audit` lists records the code or a later decision no longer
backs, with the lines citing each, and changes nothing. A team can set its own template,
extra admission triggers and retirement mode in `architecture.yaml`
(`reference/config.md`, "Decision-record keys"). The
upstream template catalog is cited by URL for you to read, under its own
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ graders:
min: 0
max: 0
arm: both
- name: lists-citation
type: regex
pattern: 'cookie_store\.py:1\b'
target: last_message
- name: lists-redis-record
type: regex
pattern: '(?:\b0001\b|ADR[- ]?0*1\b)[^\n]*\bredis\b|\bredis\b[^\n]*(?:\b0001\b|ADR[- ]?0*1\b)'
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
description: "The audit lists a record whose decided thing no longer exists in the code as a retire candidate, with evidence, and changes nothing"
description: "The audit lists a record whose decided thing no longer exists in the code as a retire candidate, with evidence and the lines citing it, and changes nothing"
tags: [architecture, record-decision, outcome, scaffold]
max_turns: 25
timeout_seconds: 600
allowed_tools: [Skill, Bash, Read, Glob, Grep, Write, Edit]
expected_outcome: "The final reply lists ADR 0001 (Redis sessions) as a retire candidate because Redis no longer exists in the code, citing the commit or search that shows it, and does not list ADR 0002 as gone. No Write or Edit call is made and no shell command removes, moves or writes a file."
expected_outcome: "The final reply lists ADR 0001 (Redis sessions) as a retire candidate because Redis no longer exists in the code, citing the commit or search that shows it, lists `src/session/cookie_store.py:1` as a line citing ADR 0001, and does not list ADR 0002 as gone. No Write or Edit call is made and no shell command removes, moves or writes a file."
---

/architecture:record-decision audit
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{
"pass": [
{
"answer": "**Gone**\n- 0001 Keep sessions in Redis: commit abc1234 removed redis.\n Cited at src/session/cookie_store.py:1: propose drop."
},
{
"answer": "ADR-1 citations: cookie_store.py:1 (drop on retirement)."
}
],
"fail": [
{
"answer": "**Gone**\n- 0001 Keep sessions in Redis: commit abc1234 removed redis."
},
{
"answer": "src/session/cookie_store.py mentions ADR 0001."
}
]
}
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ git commit -q -m "Sessions in Redis, orders in PostgreSQL"
git rm -q src/session/redis_store.py
mkdir -p src/session
cat >src/session/cookie_store.py <<'PY'
# Replaces the session store ADR 0001 chose.
"""Sessions live in signed cookies."""


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,24 @@ graders:
min: 0
max: 0
arm: both
- name: citing-file-not-edited
type: tool_used
tool: 'Edit'
input_match: '"file_path":"[^"]*schema\.graphql'
min: 0
max: 0
arm: both
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
- name: citing-file-not-overwritten
type: tool_used
tool: 'Write'
input_match: '"file_path":"[^"]*schema\.graphql'
min: 0
max: 0
arm: both
- name: lists-citation
type: regex
pattern: 'schema\.graphql:1\b'
target: last_message
- name: names-old-record
type: regex
pattern: '\b(?:ADR[- ]?0*2|0002)\b'
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
description: "A decision that reverses an existing record gets a new record naming the old one, and the old record is neither deleted, edited nor moved before the person says yes"
description: "A decision that reverses an existing record gets a new record naming the old one, the line citing the old record is listed with a proposal, and neither the old record nor the citing file changes before the person says yes"
tags: [architecture, record-decision, outcome, scaffold]
max_turns: 25
timeout_seconds: 600
allowed_tools: [Skill, Bash, Read, Glob, Grep, Write, Edit]
expected_outcome: "The run proposes or writes a new record numbered 0003 that names ADR 0002 and why it was reversed, states the retirement mode (delete by default) and its layer, and ends by asking before retiring 0002. ADR 0002 is not removed, edited or moved."
expected_outcome: "The run proposes or writes a new record numbered 0003 that names ADR 0002 and why it was reversed, states the retirement mode (delete by default) and its layer, lists `src/api/schema.graphql:1` as a line citing ADR 0002 with a proposal to point it at 0003 or drop it, and ends by asking before retiring 0002. ADR 0002 is not removed, edited or moved, and `src/api/schema.graphql` is not edited."
---

/architecture:record-decision We are reversing ADR 0002: the public API goes back to REST. Context: partners now use three fixed views, and GraphQL query cost made rate limiting unpredictable. We weighed keeping GraphQL with query cost limits and rejected it because partners could not predict their quotas. Consequences: every partner view needs a versioned endpoint, and moving back to GraphQL later means rewriting the partner SDKs.
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
{
"pass": [
{
"answer": [
{
"tool": "Edit",
"input": {
"file_path": "docs/adr/0003-serve-the-public-api-over-rest.md",
"old_string": "a",
"new_string": "b"
}
}
]
},
{
"answer": []
}
],
"fail": [
{
"answer": [
{
"tool": "Edit",
"input": {
"file_path": "src/api/schema.graphql",
"old_string": "# ADR 0002",
"new_string": "# ADR 0003"
}
}
]
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
{
"pass": [
{
"answer": [
{
"tool": "Write",
"input": {
"file_path": "docs/adr/0003-serve-the-public-api-over-rest.md",
"content": "# 3. Serve the public API over REST\n\nReverses ADR 0002.\n"
}
}
]
},
{
"answer": []
}
],
"fail": [
{
"answer": [
{
"tool": "Write",
"input": {
"file_path": "src/api/schema.graphql",
"content": "# ADR 0003\ntype Query {\n order(id: ID!): Order\n}\n"
}
}
]
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{
"pass": [
{
"answer": "Lines citing ADR 0002:\n- src/api/schema.graphql:1 `# ADR 0002`: point it at ADR 0003.\nDelete docs/adr/0002-serve-the-public-api-over-graphql.md and repoint that line?"
},
{
"answer": "Citation sweep (git grep for 0002 and the filename): schema.graphql:1, propose drop. Shall I retire 0002?"
}
],
"fail": [
{
"answer": "adr_retirement: delete (default). Delete docs/adr/0002-serve-the-public-api-over-graphql.md now?"
},
{
"answer": "The schema in src/api/schema.graphql still mentions ADR 0002; retire it?"
}
]
}
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Partners asked for flexible queries, so the public API is a GraphQL endpoint.
MD

cat >src/api/schema.graphql <<'GQL'
# ADR 0002
type Query {
order(id: ID!): Order
}
Expand Down
63 changes: 46 additions & 17 deletions plugins/architecture/skills/record-decision/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Arguments: `$ARGUMENTS`

| Action | Does |
|---|---|
| *(bare)* | Records one decision: Steps 1 to 3. The whole argument is the decision text or a file path |
| *(bare)* | Records one decision: Steps 1 to 4. The whole argument is the decision text or a file path |
| `audit` | Lists retire candidates and writes nothing: [Audit](#audit) |

Only `audit` as the first word selects the audit; any other first word is part of the decision.
Expand Down Expand Up @@ -117,9 +117,9 @@ everything Step 2 does.
4. Re-read the target directory immediately before writing, confirming no record has appeared since
Step 1 that would change the identifier.
5. Write **exactly one** new record, and report its path. Done when `git status --porcelain` shows
that one new path and nothing else, until Step 3 runs.
that one new path and nothing else, until Step 3 or Step 4 runs.

Outside Step 3, do not create, rename, or renumber any other file. Report duplicates and leave them
Outside Steps 3 and 4, do not create, rename, renumber or edit any other file. Report duplicates and leave them
where they are.

## Step 2b. No convention
Expand All @@ -136,7 +136,7 @@ where they are.
`git status --porcelain` is exactly what it was before the invocation.

When the human chooses in the same session, create only what they chose (the directory plus the
first record, its sections taken from the chosen template) and nothing else. A repository's own
first record, its sections taken from the chosen template) and nothing else, then run Step 4. A repository's own
convention, found in Step 1, always wins over `adr_template` and the bundled template.

## Step 3. Retire the record the decision replaces
Expand All @@ -146,18 +146,33 @@ person picks. The new record's `Considered options` (or the convention's equival
retired record by identifier and title and says why it was reversed.

A changed decision gets a new record, never an amendment inside the accepted one: an accepted record
is edited in place only to rename a term or to set its status.
is edited in place only to rename a term, to set its status, or to repoint a citation the sweep
below lists.

**Citation sweep.** Every retirement path runs it, whatever `adr_retirement` says: `delete` and
`archive` break a path citation, and `supersede` leaves a citation naming a decision no longer in
force. Search tracked files with `git grep -n` for the old record's identifier, in each form the
records and existing citations use (`ADR 7`, `ADR-007`, `0007`), and for its filename; report the
patterns searched. Skip the old record itself and the new record's line naming it. List each hit as
`file:line` (code, docs, skills, other records) with one proposal: point it at the new record's
identifier or path, or drop it when there is no new record or the line only made sense with the old
decision. List a changelog or release-note hit as keep: it is history. Done when every hit carries a
proposal, or the report says the search found none.

**Partial reversal.** When the new decision reverses only part of a record, keep the old file
whatever `adr_retirement` says, and in place of steps 1 to 3: after writing the new record, name the
old one and the superseded-in-part status you will set, naming the part, in the words and form the
existing records use. Ask. On a yes, edit only that status; on a no, leave it and say so. When the
records carry no such wording, say so and ask for it.

1. After writing the new record, name the old one, the resolved `adr_retirement` and its layer, and
what that will do to the old file. Ask. Act only on a yes; on a no, leave it and say so. Done
when the person has answered.
2. Retire it, done when the one change below is on disk:
existing records use, and run the citation sweep, proposing a change only for a citation of the
reversed part and listing the rest as keep. Ask. On a yes, edit that status and the proposed
citation lines only; on a no, leave them and say so. When the records carry no such wording, say so
and ask for it.

1. After writing the new record, name the old one, the resolved `adr_retirement` and its layer, what
that will do to the old file, and the citation sweep's hits with their proposals. Ask; one yes
covers the retirement and the citation edits. Act only on a yes; on a no, leave them and say so.
Done when the person has answered.
2. Retire it, and edit each proposed citation line as proposed and nothing else in those files. Done
when the citation edits and the one change below are on disk:
- `delete`: remove the file. Its number is never reused (discovery's numbering rule).
- `supersede`: set the old record's status to superseded by the new identifier, in the words and
form the existing records use; edit only that status. Retiring an audit candidate with no new
Expand All @@ -177,7 +192,17 @@ records carry no such wording, say so and ask for it.
live.

Done when `git status --porcelain` shows the new record, the one retirement or partial-status
change, and the line's file if it was written, and nothing else.
change, the files whose citations were edited, and the line's file if it was written, and nothing
else.

## Step 4. Offer a pointer comment

After a record is written, offer one pointer comment at the module or line the decision governs: one
line in that file's comment syntax, citing the record in the form the repository's records and
citations already use (its identifier, or its path), and no restated reason. Write it only after a
yes; never add one unasked. The citation sweep finds it when the record is retired, so the pointer
does not outlive its record. `/code-tidying:remove-comments` (if enabled) keeps such a pointer. Done
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
when the pointer is written or declined.

## Audit

Expand All @@ -195,13 +220,17 @@ what it was before the invocation.
record's `file:line`.
- **Fails admission**: no real alternative was weighed, or none of the "at least one" conditions
holds. Evidence: the record's `file:line`.
3. Report retire candidates grouped by those reasons, each with identifier, title and evidence, then
the count of records still backed. Offer Step 3 for the candidates the person picks; retirement
runs only there, after a yes. Done when the report is delivered.
3. Run Step 3's citation sweep for each retire candidate; the new record is a Contradicted
candidate's later record, and with none the proposal is drop. Done when every candidate has its
hits listed, or none.
4. Report retire candidates grouped by those reasons, each with identifier, title, evidence and its
citation hits, then the count of records still backed. Offer Step 3 for the candidates the person
picks; retirement and citation edits run only there, after a yes. Done when the report is
delivered.

## Hand-off

Commit the record, and any retirement, in the pull request of the change that made the decision; a
Commit the record, and any retirement, citation edits and pointer, in the pull request of the change that made the decision; a
decision with no code change gets a pull request of its own.

## Upstream template catalog
Expand Down
Loading