@codewizard-dt/bootstrap 5.1.0 → 6.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -3
- package/bin/cli.js +16 -0
- package/lib/hooks/README.md +124 -3
- package/lib/hooks/claude-settings-guard.js +8 -2
- package/lib/prompts/README.md +1 -1
- package/lib/prompts/migrate-wiki.md +7 -7
- package/lib/scripts/README.md +111 -10
- package/lib/scripts/bootstrap-prefs-tui.js +1222 -0
- package/lib/scripts/install-global.sh +137 -6
- package/lib/scripts/migrate-project.sh +52 -10
- package/lib/scripts/rename-wiki-ids.js +232 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +6 -6
- package/lib/scripts/templates/bootstrap-prefs-schema.json +11 -2
- package/lib/scripts/templates/settings-sandbox-unattended.json +36 -0
- package/lib/scripts/templates/settings-sandbox.json +7 -0
- package/lib/scripts/templates/wiki/conventions.md +12 -10
- package/lib/scripts/templates/wiki/dashboard.html +527 -23
- package/lib/scripts/templates/wiki/index.md +2 -2
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +1 -1
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -4
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +11 -9
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -4
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +8 -8
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +11 -3
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +7 -5
- package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +16 -8
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +3 -3
- package/lib/scripts/wiki-dashboard-server.js +98 -0
- package/lib/skills/README.md +27 -22
- package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +103 -0
- package/lib/skills/_shared/ID-RESOLUTION.md +142 -0
- package/lib/skills/_shared/SKILL-BOILERPLATE.md +50 -0
- package/lib/skills/adr-assess/SKILL.md +112 -0
- package/lib/skills/{decision-create → adr-create}/SKILL.md +27 -26
- package/lib/skills/adr-deprecate/SKILL.md +190 -0
- package/lib/skills/adr-extract/SKILL.md +255 -0
- package/lib/skills/{decision-finalize → adr-finalize}/SKILL.md +38 -38
- package/lib/skills/{decision-next → adr-next}/SKILL.md +20 -19
- package/lib/skills/{decision-walkthrough → adr-walkthrough}/SKILL.md +23 -29
- package/lib/skills/architecture-audit/SKILL.md +24 -3
- package/lib/skills/autopilot/SKILL.md +110 -0
- package/lib/skills/bootstrap-config/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +3 -3
- package/lib/skills/bug-close/SKILL.md +15 -26
- package/lib/skills/{bug-file → bug-create}/SKILL.md +25 -15
- package/lib/skills/bug-triage/SKILL.md +5 -19
- package/lib/skills/demo/SKILL.md +11 -11
- package/lib/skills/elevator-pitch/SKILL.md +1 -1
- package/lib/skills/extract-feature/SKILL.md +29 -87
- package/lib/skills/git-commit/SKILL.md +4 -4
- package/lib/skills/marp-slideshow/SKILL.md +2 -2
- package/lib/skills/port-feature/SKILL.md +28 -83
- package/lib/skills/power-mode/SKILL.md +42 -49
- package/lib/skills/prd-assess/SKILL.md +105 -0
- package/lib/skills/{req-compile → prd-compile}/SKILL.md +6 -13
- package/lib/skills/{req-create → prd-create}/SKILL.md +19 -19
- package/lib/skills/prd-deprecate/SKILL.md +173 -0
- package/lib/skills/{req-finalize → prd-finalize}/SKILL.md +20 -29
- package/lib/skills/primer/SKILL.md +2 -2
- package/lib/skills/research/SKILL.md +3 -3
- package/lib/skills/roadmap-assess/SKILL.md +20 -20
- package/lib/skills/roadmap-create/SKILL.md +23 -29
- package/lib/skills/roadmap-next/SKILL.md +16 -28
- package/lib/skills/security-audit/SKILL.md +3 -3
- package/lib/skills/tackle/SKILL.md +13 -15
- package/lib/skills/{task-audit → task-assess}/SKILL.md +34 -44
- package/lib/skills/task-close/SKILL.md +73 -0
- package/lib/skills/{task-add → task-create}/SKILL.md +44 -24
- package/lib/skills/uat-assess/SKILL.md +124 -0
- package/lib/skills/uat-auto/SKILL.md +9 -6
- package/lib/skills/uat-auto-plus/SKILL.md +2 -2
- package/lib/skills/{uat-generate → uat-create}/SKILL.md +10 -12
- package/lib/skills/uat-skip/SKILL.md +5 -9
- package/lib/skills/uat-walk/SKILL.md +2 -2
- package/lib/skills/uat-walk/UAT-CORE.md +29 -16
- package/lib/skills/update-docs/SKILL.md +1 -1
- package/lib/skills/usage-report/SKILL.md +52 -0
- package/lib/skills/usage-report/scripts/pricing.json +22 -0
- package/lib/skills/usage-report/scripts/usage-report.js +518 -0
- package/lib/skills/whats-next/SKILL.md +177 -0
- package/lib/skills/wiki-archive/SKILL.md +12 -23
- package/lib/skills/wiki-lint/SKILL.md +42 -5
- package/lib/skills/wiki-query/SKILL.md +1 -1
- package/lib/skills/wiki-rotate-log/SKILL.md +1 -1
- package/lib/skills/wiki-tidy/SKILL.md +6 -9
- package/package.json +1 -1
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +0 -10
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +0 -10
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +0 -10
- package/lib/skills/req-extract-decisions/SKILL.md +0 -241
- package/lib/skills/req-retire/SKILL.md +0 -185
- package/lib/skills/req-update/SKILL.md +0 -265
- package/lib/skills/task-trash/SKILL.md +0 -115
- package/lib/skills/task-update/SKILL.md +0 -136
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: adr-deprecate
|
|
3
|
+
description: Deprecate a single ADR decision block — set Status to deprecated, document the reason, update the family index, append a log entry. Status-only: the file never moves.
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-haiku-4-5-20251001
|
|
6
|
+
argument-hint: <ADR-NNNN#DM | NNNN-slug#DM | path#DM> [reason]
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
**Read `wiki/work/decisions/lifecycle.md` first** — it defines the Decision Group model, the per-decision status lifecycle, and the terminal states.
|
|
12
|
+
|
|
13
|
+
# Deprecate ADR
|
|
14
|
+
|
|
15
|
+
Set a **single decision block's** `Status` to `deprecated`, document why, and update the decision group's row in the family index. A Decision Group has no group-level status — each `## DM.` block carries its own `Status:` — so this skill works per decision, and **sibling blocks are never touched**. The file stays in `wiki/work/decisions/`, so cross-references using `[[ADR-NNNN]]` and `ADR-NNNN#DM` (and legacy `DEC-NNNN` links, which still resolve) are unaffected.
|
|
16
|
+
|
|
17
|
+
`deprecated` withdraws a decision **without a successor**: a `proposed` decision is abandoned, or an `accepted` decision is withdrawn. When a replacement decision exists, do not use this skill — write it with `/adr-create` and let `/adr-finalize` supersede the old block. **`superseded` is set only by `/adr-finalize` — never by this skill.**
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
**ADR**: $ARGUMENTS
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Instructions
|
|
26
|
+
|
|
27
|
+
### Step 1: Resolve the file and the decision
|
|
28
|
+
|
|
29
|
+
Parse `$ARGUMENTS`:
|
|
30
|
+
- **First token(s)** — the reference: `<path>#DM`, `ADR-NNNN#DM`, `<NNNN-slug>#DM`, or the same without the suffix
|
|
31
|
+
- **Remaining text** — optional reason for deprecation (may be elicited in Step 3 if absent)
|
|
32
|
+
|
|
33
|
+
Resolve the file per ~/.claude/skills/_shared/ID-RESOLUTION.md — family: decisions · scope: active · ambiguous: interactive · empty: list every Decision Group in `wiki/work/decisions/` and ask the user via `AskUserQuestion` to pick
|
|
34
|
+
|
|
35
|
+
The `#DM` suffix is split off and handed back per that doc's **`#DM` suffix** section; decision = `DM`. Both `ADR-NNNN` and legacy `DEC-NNNN` references are accepted.
|
|
36
|
+
|
|
37
|
+
| Input | Resolution |
|
|
38
|
+
|-------|------------|
|
|
39
|
+
| `#DM` given | decision = `DM` |
|
|
40
|
+
| No `#DM`, group has exactly **one** non-terminal block (`proposed` or `accepted`) | default to it, after the user confirms in Step 3 |
|
|
41
|
+
| No `#DM`, group has **several** non-terminal blocks | list them and ask via `AskUserQuestion` which one |
|
|
42
|
+
|
|
43
|
+
An item still sitting in a legacy holding folder from the older layout is already terminal: if the resolver STOPs and the ID appears in that legacy folder's index, report "already closed" instead of "not found".
|
|
44
|
+
|
|
45
|
+
If the file or the decision block cannot be located, **stop** and report — never invent or create.
|
|
46
|
+
|
|
47
|
+
### Step 2: Read the group and verify the block's status
|
|
48
|
+
|
|
49
|
+
1. **Read** the group file with `Read`; locate the `## DM. <title>` H2 and everything up to the next `## D*` or end of file.
|
|
50
|
+
2. **Check that block's `Status:`:**
|
|
51
|
+
|
|
52
|
+
| Current status | Action |
|
|
53
|
+
|----------------|--------|
|
|
54
|
+
| `proposed` | Continue — abandon a draft decision |
|
|
55
|
+
| `accepted` | Continue — withdraw a decision with no successor |
|
|
56
|
+
| `deprecated` | **STOP.** Tell the user: "ADR-NNNN#DM is already deprecated. No action needed." |
|
|
57
|
+
| `superseded by …` | **STOP.** Tell the user: "ADR-NNNN#DM is already superseded — it is no longer authoritative." Point at the successor named in the status. |
|
|
58
|
+
|
|
59
|
+
3. **Find downstream artifacts** (Serena `search_for_pattern`, read-only):
|
|
60
|
+
- Other blocks (in this group or any other) whose `Supersedes:` names `ADR-NNNN#DM` (or its legacy `DEC-NNNN#DM` form), or that link to it in `### Links`
|
|
61
|
+
- Tasks with `implements::[[ADR-NNNN#DM]]` in `wiki/work/tasks/`, plus the block's own `Source task(s):` links
|
|
62
|
+
- Build a downstream artifacts table for Step 3
|
|
63
|
+
|
|
64
|
+
### Step 3: Confirm with the user
|
|
65
|
+
|
|
66
|
+
Use `AskUserQuestion` to confirm. Show:
|
|
67
|
+
|
|
68
|
+
- The group file (full path), the `ADR-NNNN#DM` ID, and the decision title
|
|
69
|
+
- The block's current status
|
|
70
|
+
- Downstream artifacts table (if any):
|
|
71
|
+
|
|
72
|
+
| Artifact | Type | Current status | Suggested action |
|
|
73
|
+
|----------|------|----------------|------------------|
|
|
74
|
+
| `[[ADR-0009-caching\|ADR-0009#D1]]` | dependent decision | accepted | Review independently — it may rest on the withdrawn decision; this skill never edits it |
|
|
75
|
+
| `[[0042-cache-layer\|TASK-0042]]` | linked task | todo | Run `/task-close wiki/work/tasks/TASK-0042-cache-layer.md` if the task is also cancelled |
|
|
76
|
+
|
|
77
|
+
Ask the user:
|
|
78
|
+
|
|
79
|
+
1. **"Deprecate ADR-NNNN#DM? (yes / no)"**
|
|
80
|
+
2. **"Reason for deprecating ADR-NNNN#DM?"** (if not provided in `$ARGUMENTS` — required, one line or more)
|
|
81
|
+
|
|
82
|
+
If the user says **No**, STOP. Do not proceed.
|
|
83
|
+
|
|
84
|
+
If a replacement decision exists or is wanted, say so and suggest `/adr-create <topic> (supersedes ADR-NNNN#DM)` followed by `/adr-finalize` instead — that is the supersession path, and it is not this skill.
|
|
85
|
+
|
|
86
|
+
**Do NOT ask whether to close linked tasks or edit dependent decisions** — they are surfaced as suggestions only. This skill never auto-cascades.
|
|
87
|
+
|
|
88
|
+
### Step 4: Apply the deprecation edits
|
|
89
|
+
|
|
90
|
+
Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md § Edit hygiene`. **Touch only the target block; sibling decisions are inviolate.**
|
|
91
|
+
|
|
92
|
+
Apply in this order:
|
|
93
|
+
|
|
94
|
+
1. **Block `Status:` → `deprecated`** (`- **Status**: <current>` becomes `- **Status**: deprecated`).
|
|
95
|
+
2. **Insert the callout directly under that decision's H2** — between the H2 and its metadata bullets, the same placement `/adr-finalize` uses for its supersession callout, so a reader sees it first:
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
> **Deprecated** on YYYY-MM-DD: <reason provided by user>
|
|
99
|
+
```
|
|
100
|
+
3. **Update the group frontmatter `updated:`** (or the `Last updated` line, whichever the file carries) to today's date — the only file-level edit.
|
|
101
|
+
4. **Keep the index and graph sections in agreement.** If the group file or `wiki/work/decisions/lifecycle.md` carries the sections `/adr-finalize` maintains — an Index table with a `Status` column and a `Relationship Graph` mermaid block with `class` lines — flip the target row's `Status` to `deprecated` and the target node's class to `deprecated`. Define a `deprecated` class in the graph only if the graph already declares classes; otherwise reuse `superseded`'s style. Verify all sections agree before saving (an index saying `deprecated` while the graph shows the node `accepted` is a broken commit). If neither carries these sections, skip this item.
|
|
102
|
+
|
|
103
|
+
The block's content is otherwise untouched: an accepted decision is immutable except for this status change and its callout.
|
|
104
|
+
|
|
105
|
+
### Step 5: Update the family index
|
|
106
|
+
|
|
107
|
+
Update the group's row in `wiki/work/decisions/index.md`. Its trailing per-block summary lists each block's status (`D1 proposed, D2 deprecated, …`) — change the target block's entry to `deprecated`.
|
|
108
|
+
|
|
109
|
+
Then place the row by the rule for decisions: a group is Active while any block is `proposed`. Moving a row to Closed is the in-place close mechanic defined once in `~/.claude/skills/_shared/ARCHIVE-WORK-ITEM.md` § In-place close (roadmaps, decisions, requirements) with `family: decisions` (the block `Status:` was already set in Step 4, and Step 6 writes this skill's own log entry).
|
|
110
|
+
|
|
111
|
+
| State after the flip | Row placement |
|
|
112
|
+
|----------------------|---------------|
|
|
113
|
+
| At least one block still `proposed` | Leave the row in Active |
|
|
114
|
+
| No block remains `proposed` | Move the row from Active to the `## Closed` section |
|
|
115
|
+
|
|
116
|
+
When moving, delete the row from Active and add the same entry under a `## Closed` heading, using the Active bullet format (the trailing per-block summary carries the terminal statuses):
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
- [ADR-NNNN — Title](ADR-NNNN-slug.md) — one-line summary · D1 accepted, D2 deprecated
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
If the index has no `## Closed` heading yet, create it at the end of the file (with the entry-format line if the Active section carries one). Keep Closed rows in numeric-ID order. If the row is already in Closed (an accepted block deprecated in an already-closed group), only update its summary.
|
|
123
|
+
|
|
124
|
+
Use `Read` then `Edit`. If the row is absent, note it and continue.
|
|
125
|
+
|
|
126
|
+
### Step 6: Append to wiki/log.md
|
|
127
|
+
|
|
128
|
+
Append one entry to `wiki/log.md`:
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
## [YYYY-MM-DD] adr-deprecated | ADR-NNNN#DM <title> — reason: <one-line summary of reason>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Use `Read` then `Edit`.
|
|
135
|
+
|
|
136
|
+
### Step 7: Surface downstream artifacts for independent action
|
|
137
|
+
|
|
138
|
+
Print the downstream artifacts table from Step 3 again, with suggested next-action commands:
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
Linked tasks and dependent decisions surfaced for independent review:
|
|
142
|
+
|
|
143
|
+
To act on linked tasks (each independently):
|
|
144
|
+
/task-close wiki/work/tasks/TASK-0042-cache-layer.md # if the task is also cancelled
|
|
145
|
+
|
|
146
|
+
To act on dependent decisions (each independently):
|
|
147
|
+
# Accepted decisions are immutable — review whether they still hold;
|
|
148
|
+
# if one should change, write a successor with /adr-create and finalize it
|
|
149
|
+
/adr-create <topic> (supersedes ADR-0009#D1)
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Step 8: Report completion
|
|
153
|
+
|
|
154
|
+
Print a tabular summary:
|
|
155
|
+
|
|
156
|
+
| Field | Value |
|
|
157
|
+
|-------|-------|
|
|
158
|
+
| Decision | `ADR-NNNN#DM <title>` |
|
|
159
|
+
| File path | `wiki/work/decisions/ADR-NNNN-slug.md` (unchanged) |
|
|
160
|
+
| Old status | `proposed` or `accepted` |
|
|
161
|
+
| New status | `deprecated` |
|
|
162
|
+
| Reason | <one-line summary> |
|
|
163
|
+
| Family index updated | yes (row stays in Active / row moved to Closed / summary only) |
|
|
164
|
+
| wiki/log.md entry | yes |
|
|
165
|
+
| Dependent decisions surfaced | count |
|
|
166
|
+
| Linked tasks surfaced | count |
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## Output Formatting Rules
|
|
171
|
+
|
|
172
|
+
1. Use tables for the downstream artifacts list and the completion report — never paragraph prose.
|
|
173
|
+
2. **One `Edit` call per change** — never bulk rewrites.
|
|
174
|
+
3. **The file never moves**, so all ID cross-references remain valid.
|
|
175
|
+
4. **The skill never auto-closes tasks or edits dependent decisions** — it surfaces them with suggested commands.
|
|
176
|
+
5. **The deprecation callout is permanent** — it is the audit trail for why this decision was withdrawn.
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
## CRITICAL Rules
|
|
181
|
+
|
|
182
|
+
1. **Status-only.** Set the block's `Status: deprecated`, add the callout, and update the index; **never move the file**, and this skill needs no shell access — it is pure `Read` and `Edit`.
|
|
183
|
+
2. **Touch only the target block.** Sibling decisions in the group stay byte-for-byte unchanged.
|
|
184
|
+
3. **`superseded` is set only by `/adr-finalize`** — never by this skill. A decision with a successor goes through `/adr-create` then `/adr-finalize`.
|
|
185
|
+
4. **Never auto-cascade** to linked tasks or dependent decisions. Surface them as suggestions only (`/task-close <path>`, independent review).
|
|
186
|
+
5. **Confirm with the user before any edits** — `AskUserQuestion` is mandatory in Step 3.
|
|
187
|
+
6. **Deprecation reason is required** — refuse to deprecate without a documented reason.
|
|
188
|
+
7. **Refuse if already `deprecated` or `superseded`** — these are terminal states; running again is a no-op, not an error.
|
|
189
|
+
8. Maximum 3 sub-processes at a time if delegating any step.
|
|
190
|
+
9. Always terminate background processes when done.
|
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: adr-extract
|
|
3
|
+
description: Extract Architecturally Significant Requirements from a PRD (or any document), cross-check existing ADRs, and propose Decision Group candidates for /adr-create
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-opus-5
|
|
6
|
+
effort: high
|
|
7
|
+
argument-hint: <PRD ID / NNNN-slug / NNNN / path, or path to any document>
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
# ADR Candidates from a Source Document
|
|
15
|
+
|
|
16
|
+
Bridge a **PRD (must be `approved`) or any other document** into the architectural decision pipeline. This skill walks the source, extracts **Architecturally Significant Requirements (ASRs)**, cross-checks them against the existing ADR log, and groups remaining ASRs into Decision Group candidates. In **PRD mode** it writes both sides of the bidirectional cross-link: placeholder rows in the PRD's `## Linked Decisions` table and `Source PRD:` back-links on any existing ADR that already covers an ASR. In **document mode** it is read-only apart from the log entry.
|
|
17
|
+
|
|
18
|
+
This skill **never** invokes `/adr-create` itself. It surfaces the commands the user runs next, one per confirmed Decision Group. The user remains in control of which decisions to write, when, and with what scope.
|
|
19
|
+
|
|
20
|
+
**Check `wiki/work/decisions/lifecycle.md` AND `wiki/work/decisions/` first.** The lifecycle defines the decision format; recent decision files show the wikilink format and the ASR taxonomy. In PRD mode, the PRD's `## Linked Decisions` table is the other side of the linkage.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
**Target**: $ARGUMENTS
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Instructions
|
|
29
|
+
|
|
30
|
+
### Step 1: Resolve the source
|
|
31
|
+
|
|
32
|
+
Pick the mode from the argument **before any lookup**:
|
|
33
|
+
|
|
34
|
+
| Argument | Mode | Resolution |
|
|
35
|
+
|----------|------|------------|
|
|
36
|
+
| Empty, an ID (`PRD-NNNN`, legacy `REQ-NNNN`), `NNNN-slug`, or a bare number | **PRD mode** | Resolve via ID-RESOLUTION (below) |
|
|
37
|
+
| A path under `wiki/work/requirements/` | **PRD mode** | Resolve via ID-RESOLUTION (below) |
|
|
38
|
+
| A path (contains `/` or ends `.md`) **not** under `wiki/work/requirements/` | **Document mode** | Confirm the file exists with `find_file`; skip ID-RESOLUTION and the status gate |
|
|
39
|
+
|
|
40
|
+
**PRD mode:** Resolve the file per ~/.claude/skills/_shared/ID-RESOLUTION.md — family: requirements · scope: active · ambiguous: interactive · empty: list every requirement in `wiki/work/requirements/` whose `status` is `approved`, one row per file, and ask the user via `AskUserQuestion` to pick one
|
|
41
|
+
|
|
42
|
+
**Document mode:** if the file does not exist, **stop** with `File not found: <path>` — never create it.
|
|
43
|
+
|
|
44
|
+
If the file cannot be located, **stop** and report — do not invent or create.
|
|
45
|
+
|
|
46
|
+
### Step 2: Verify the source is eligible
|
|
47
|
+
|
|
48
|
+
**Document mode** has no status gate — continue to Step 3.
|
|
49
|
+
|
|
50
|
+
**PRD mode:** read the PRD's frontmatter `status` field. Refuse to continue with explicit guidance for any non-approved status:
|
|
51
|
+
|
|
52
|
+
| Current Status | Action |
|
|
53
|
+
|----------------|--------|
|
|
54
|
+
| `approved` | Continue to Step 3 |
|
|
55
|
+
| `draft` | Stop. Tell the user: "This PRD is still in draft. Run `/prd-finalize <path>` first, then re-run `/adr-extract`." |
|
|
56
|
+
| `retired` | Stop. Tell the user: "This PRD is retired. If a new architectural decision is needed, write a new PRD via `/prd-create`." |
|
|
57
|
+
| `superseded` | Stop. Tell the user: "This PRD has been superseded. Run `/adr-extract` against the successor PRD instead." |
|
|
58
|
+
|
|
59
|
+
### Step 3: Read the source and extract ASR candidates
|
|
60
|
+
|
|
61
|
+
Walk the source section by section and identify statements that imply architectural decisions. Use the ASR taxonomy — anything that affects structure, NFRs, dependencies, interfaces, construction techniques, or hard-to-reverse choices.
|
|
62
|
+
|
|
63
|
+
Scan with this map. For a non-PRD document, scan every heading section with the same taxonomy; the Source Section column carries the document's own section title.
|
|
64
|
+
|
|
65
|
+
| Source Section | What to scan for | Likely decision category |
|
|
66
|
+
|----------------|------------------|--------------------------|
|
|
67
|
+
| Problem Statement | Mentions of scale, latency, integration boundaries, multi-tenancy | Structure, NFRs |
|
|
68
|
+
| Goals + Success Metrics | Quantitative thresholds (p95 latency, throughput, availability, error budget) | NFRs |
|
|
69
|
+
| User Stories acceptance criteria | Cross-system integrations, real-time requirements, transactional boundaries | Interfaces, NFRs |
|
|
70
|
+
| Constraints | Regulatory, compliance, vendor-mandated, contractual | Dependencies, security |
|
|
71
|
+
| Assumptions | Existing-system dependencies the source relies on | Dependencies |
|
|
72
|
+
| Non-Goals | What is NOT being built — informs scope of decisions, prevents over-broad decisions | Scope-bounding |
|
|
73
|
+
|
|
74
|
+
Build a candidate-ASR table. Every row must trace to a specific source location — quote or paraphrase verbatim, never invent:
|
|
75
|
+
|
|
76
|
+
| ASR# | ASR Statement (from source) | Source Section | Likely Decision Area | Likely Category |
|
|
77
|
+
|------|-----------------------------|----------------|----------------------|-----------------|
|
|
78
|
+
| A1 | "p95 search latency < 200ms with 10k active users" | SM-2 | search-infrastructure | NFR / Structure |
|
|
79
|
+
| A2 | "Must comply with SOC 2 access controls" | Constraint 1 | auth-and-access | Dependencies / Security |
|
|
80
|
+
| A3 | "Onboarding flow integrates with HRIS providers" | US-3 AC#2 | hris-integration | Interfaces |
|
|
81
|
+
|
|
82
|
+
**Boundary enforcement:** If an ASR statement smuggles a solution ("use Redis", "switch to GraphQL"), reformulate it as the underlying outcome ("session lookups must be < 5ms p99", "client schemas must evolve without redeploys") before adding it to the table.
|
|
83
|
+
|
|
84
|
+
If a candidate is borderline, exclude it and note the exclusion.
|
|
85
|
+
|
|
86
|
+
### Step 4: Cross-check existing decisions
|
|
87
|
+
|
|
88
|
+
For each candidate ASR, check whether an existing `accepted` decision already covers it.
|
|
89
|
+
|
|
90
|
+
**Procedure:**
|
|
91
|
+
|
|
92
|
+
1. `mcp__serena__list_dir` on `wiki/work/decisions/` to enumerate decision files (fully-decided groups stay in this directory, listed under `## Closed` in the index; include a legacy holding subfolder if one exists)
|
|
93
|
+
2. `Read` each decision file and walk every `## D*` block; collect blocks where `status: accepted` (or recently `proposed`) — select by block status, never by directory or index section
|
|
94
|
+
3. For each candidate ASR, score each decision block using Tier-1 tag-overlap signal:
|
|
95
|
+
|
|
96
|
+
| Tier | Signal | Detection |
|
|
97
|
+
|------|--------|-----------|
|
|
98
|
+
| 1 | Tag overlap on the decision block | ≥ 1 shared tag with the ASR's likely decision area |
|
|
99
|
+
| 2 | Decision sub-title noun-phrase overlap | Substantial overlap |
|
|
100
|
+
| 3 | File-slug stem overlap | Only when the decision is a single-decision file |
|
|
101
|
+
|
|
102
|
+
4. Build the existing-coverage table:
|
|
103
|
+
|
|
104
|
+
| ASR# | Existing Decision Coverage | Coverage Status | Action |
|
|
105
|
+
|------|---------------------------|-----------------|--------|
|
|
106
|
+
| A1 | none | — | propose new decision |
|
|
107
|
+
| A2 | [[ADR-0003-auth-and-access\|ADR-0003#D2]] (tags: auth, soc2) | accepted | reuse — no new decision; add Source PRD back-link (PRD mode) |
|
|
108
|
+
| A3 | [[ADR-0005-integrations\|ADR-0005#D1]] (tags: hris) | proposed | propose new decision if A3's scope is broader |
|
|
109
|
+
|
|
110
|
+
A `proposed` candidate is **not** a substitute for new coverage — flag it for the user.
|
|
111
|
+
|
|
112
|
+
### Step 5: Group ASRs into Decision Group candidates
|
|
113
|
+
|
|
114
|
+
Group ASRs **not already covered** by accepted decisions.
|
|
115
|
+
|
|
116
|
+
Group when shared context, deciders, or tight coupling argues for one file. Split when decision areas, audiences, or timelines diverge. Default to splitting when in doubt.
|
|
117
|
+
|
|
118
|
+
Output the proposed grouping table:
|
|
119
|
+
|
|
120
|
+
| Group | ASRs | Suggested Decision Slug | Rationale (group/split signal) |
|
|
121
|
+
|-------|------|-----------------------|--------------------------------|
|
|
122
|
+
| G1 | A1 | search-infrastructure | Single decision area, single decider set |
|
|
123
|
+
| G2 | A3 | hris-integration | Distinct decision area; different reviewers from G1 |
|
|
124
|
+
|
|
125
|
+
### Step 6: Present and confirm via `AskUserQuestion`
|
|
126
|
+
|
|
127
|
+
Show the user three tables in this order:
|
|
128
|
+
|
|
129
|
+
1. The full ASR table from Step 3 (with the existing-coverage column folded in from Step 4)
|
|
130
|
+
2. The proposed grouping from Step 5
|
|
131
|
+
3. A per-group action prompt
|
|
132
|
+
|
|
133
|
+
For **each proposed group**, ask: "Create this as a decision now?" with options:
|
|
134
|
+
|
|
135
|
+
| Option | Meaning |
|
|
136
|
+
|--------|---------|
|
|
137
|
+
| `yes` | Confirm the group; in PRD mode the skill will write a placeholder row in the PRD and the user will run `/adr-create` next |
|
|
138
|
+
| `defer` | Keep the ASRs in the PRD's `## Linked Decisions` table as `not yet created` (document mode: list them in the report) |
|
|
139
|
+
| `merge into <Gx>` | Combine this group with another listed group |
|
|
140
|
+
| `split` | Break this group into multiple smaller groups |
|
|
141
|
+
| `skip — already covered` | Drop the group; the ASR is handled by an existing decision |
|
|
142
|
+
| `skip — non-architectural` | Drop the group; handle directly via `/task-create` (`--req PRD-NNNN` when the source is a PRD) |
|
|
143
|
+
|
|
144
|
+
### Step 7: Update the PRD's Linked-Decisions section (PRD mode only)
|
|
145
|
+
|
|
146
|
+
**Document mode** skips this step: there is no PRD to hold the table. Print the same table in the Step 9 report instead, and append only the log entry below.
|
|
147
|
+
|
|
148
|
+
**PRD mode:** use `Read` then `Edit` to populate the PRD's `## Linked Decisions` table. The edit is **surgical** — replace only the placeholder row inside that section.
|
|
149
|
+
|
|
150
|
+
For each row in the confirmed plan, use **wikilink format** for existing decisions:
|
|
151
|
+
|
|
152
|
+
| ASR | Decision | Status |
|
|
153
|
+
|-----|----------|--------|
|
|
154
|
+
| A1: <verbatim statement> | _to be created via `/adr-create group: search-infrastructure`_ | not yet created |
|
|
155
|
+
| A2: <verbatim statement> | `[[ADR-0003-auth-and-access\|ADR-0003#D2]]` | accepted |
|
|
156
|
+
| A3: <verbatim statement> | _to be created via `/adr-create hris-integration`_ | not yet created |
|
|
157
|
+
|
|
158
|
+
Rules for the row content:
|
|
159
|
+
|
|
160
|
+
| Column | Rule |
|
|
161
|
+
|--------|------|
|
|
162
|
+
| `ASR` | The ASR ID and verbatim (or near-verbatim) statement from Step 3 |
|
|
163
|
+
| `Decision` | If covered by existing decision: wikilink `[[ADR-NNNN-slug\|ADR-NNNN#DM]]` (a not-yet-migrated file keeps its legacy `DEC-NNNN` form). If creating new: italicized placeholder with the exact `/adr-create` command |
|
|
164
|
+
| `Status` | `accepted` / `proposed` / `not yet created` |
|
|
165
|
+
|
|
166
|
+
Also update the PRD's frontmatter `updated` to today's date. Both edits use `Read` + `Edit`.
|
|
167
|
+
|
|
168
|
+
Append to `wiki/log.md` (re-read it immediately before editing) — both modes:
|
|
169
|
+
|
|
170
|
+
```
|
|
171
|
+
## [YYYY-MM-DD] adr-extract | <PRD-NNNN or document path> <title> — N ASRs identified
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Step 8: Update existing ADRs that reuse source ASRs (PRD mode only)
|
|
175
|
+
|
|
176
|
+
**Document mode** skips this step.
|
|
177
|
+
|
|
178
|
+
For each ASR marked as "covered by existing decision" in Step 4 and confirmed by the user in Step 6, edit the referenced decision's `### Links` section to add a `Source PRD:` line.
|
|
179
|
+
|
|
180
|
+
For each affected decision file:
|
|
181
|
+
|
|
182
|
+
1. `Read` the file
|
|
183
|
+
2. Locate the target decision's `### Links` section
|
|
184
|
+
3. Check whether a `Source PRD:` line **or a legacy `Source REQ:` line** for the same item (matched by its current ID or an alias) already exists — **skip if present** (idempotent)
|
|
185
|
+
4. `Edit` to append: `- Source PRD: [PRD-NNNN](../requirements/PRD-NNNN-slug.md)`
|
|
186
|
+
|
|
187
|
+
Touch only the target decision's `### Links`. Do not modify any decision's status, metadata, or content beyond the `### Links` append.
|
|
188
|
+
|
|
189
|
+
### Step 9: Report and instruct
|
|
190
|
+
|
|
191
|
+
Print a tabular completion report:
|
|
192
|
+
|
|
193
|
+
| Field | Value |
|
|
194
|
+
|-------|-------|
|
|
195
|
+
| Source | `PRD-NNNN <title>` or the document path |
|
|
196
|
+
| Source mode | `PRD` / `document` |
|
|
197
|
+
| ASRs identified | count |
|
|
198
|
+
| ASRs covered by existing decisions | count (linked back in PRD mode) |
|
|
199
|
+
| New decision groups proposed | count |
|
|
200
|
+
| New decision groups confirmed by user | count |
|
|
201
|
+
| ASRs deferred | count |
|
|
202
|
+
| ASRs skipped as non-architectural | count |
|
|
203
|
+
| PRD Linked-Decisions table updated | yes (PRD mode) / n/a (document mode) |
|
|
204
|
+
| Existing decision back-links added | count (PRD mode) / n/a (document mode) |
|
|
205
|
+
| Log entry | appended to wiki/log.md |
|
|
206
|
+
|
|
207
|
+
Then list the **next-action commands**, one per confirmed new group. In document mode, suffix each `(from <document path>)`:
|
|
208
|
+
|
|
209
|
+
```
|
|
210
|
+
To create the proposed decisions, run each:
|
|
211
|
+
/adr-create group: search-infrastructure (from PRD-NNNN)
|
|
212
|
+
/adr-create hris-integration (from PRD-NNNN)
|
|
213
|
+
|
|
214
|
+
After each /adr-create completes, return to PRD-NNNN's `## Linked Decisions` table
|
|
215
|
+
and update the placeholder row with the actual wikilink [[ADR-NNNN-slug|ADR-NNNN#DM]].
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
(The return-to-the-table note applies in PRD mode only.)
|
|
219
|
+
|
|
220
|
+
If any ASRs were skipped as non-architectural, also surface. In PRD mode:
|
|
221
|
+
|
|
222
|
+
```
|
|
223
|
+
The following ASRs are best handled directly as tasks (no decision needed):
|
|
224
|
+
/task-create --req PRD-NNNN "<short description for ASR Ax>"
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
In document mode, list those ASRs in a plain list without a `--req` form.
|
|
228
|
+
|
|
229
|
+
The skill does **not** auto-invoke `/adr-create` or `/task-create`. It surfaces the commands; the user runs them.
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Output Formatting Rules (mandatory)
|
|
234
|
+
|
|
235
|
+
1. **Tables, not bullets.** ASR identification, existing-coverage analysis, and grouping proposals are all tables.
|
|
236
|
+
2. **Never auto-invoke `/adr-create` or `/task-create`.** Surface the exact commands; the user runs them.
|
|
237
|
+
3. **Never invent ASRs.** Every entry in the ASR table must trace to a specific source section, quoted or paraphrased verbatim.
|
|
238
|
+
4. **Boundary rule is enforced strictly.** Sources ask for outcomes, decisions admit trade-offs. If a candidate ASR sounds like a solution, reformulate it as the underlying outcome.
|
|
239
|
+
5. **PRD edits are surgical.** Use `Read` then `Edit` to update only the `## Linked Decisions` table and the `updated` field. Never rewrite the file.
|
|
240
|
+
6. **Idempotent back-links.** If a `Source PRD:` line (or a legacy `Source REQ:` line) for the same item already exists in a decision's `### Links`, skip the edit. Re-running this skill against the same PRD must not duplicate links.
|
|
241
|
+
7. **Wikilinks for existing decisions.** Use `[[ADR-NNNN-slug\|ADR-NNNN#DM]]` format in the `## Linked Decisions` table.
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## CRITICAL Rules
|
|
246
|
+
|
|
247
|
+
1. **Refuse to run on a PRD not in `approved` status.** Step 2 is a hard gate (document mode has no status gate).
|
|
248
|
+
2. **Never invent ASRs.** Every candidate is grounded in a specific source section.
|
|
249
|
+
3. **Never auto-create decisions.** Surface them as commands the user runs.
|
|
250
|
+
4. **Cross-check existing decisions before proposing duplicates.** Step 4 is mandatory.
|
|
251
|
+
5. **Bidirectional linkage is the contract in PRD mode.** The PRD's `## Linked Decisions` and any existing decision's `### Links` must both reflect the relationship. Re-running is idempotent. Document mode is read-only apart from the log entry.
|
|
252
|
+
6. **Per-decision tag overlap is the existing-coverage signal.**
|
|
253
|
+
7. **Maximum 3 sub-processes at a time** if delegating research or coverage analysis.
|
|
254
|
+
8. **Always terminate processes when done.**
|
|
255
|
+
9. Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
2
|
+
name: adr-finalize
|
|
3
3
|
description: Finalize a single proposed decision block; run E-C-A-D-R audit, supersession check, and flip status to accepted
|
|
4
4
|
category: planning
|
|
5
5
|
model: claude-sonnet-5
|
|
@@ -15,7 +15,7 @@ user-invocable: true
|
|
|
15
15
|
|
|
16
16
|
Take a **single proposed decision block** in a decision file, surface every open question/placeholder, ratify it with the user, **enforce the supersession rule** against any prior accepted decision in the same area, then flip *that decision's* status to **accepted**.
|
|
17
17
|
|
|
18
|
-
Each decision is finalized **independently** — a file with three proposed decisions takes three invocations; **sibling decisions are never touched**. Once accepted, a decision is immutable; to change it, write a successor via `/
|
|
18
|
+
Each decision is finalized **independently** — a file with three proposed decisions takes three invocations; **sibling decisions are never touched**. Once accepted, a decision is immutable; to change it, write a successor via `/adr-create` and finalize it to supersede the old one.
|
|
19
19
|
|
|
20
20
|
**Target**: $ARGUMENTS
|
|
21
21
|
|
|
@@ -23,21 +23,23 @@ Each decision is finalized **independently** — a file with three proposed deci
|
|
|
23
23
|
|
|
24
24
|
## Step 1: Locate the (file, decision) pair
|
|
25
25
|
|
|
26
|
+
Resolve the file per ~/.claude/skills/_shared/ID-RESOLUTION.md — family: decisions · scope: active · ambiguous: interactive · empty: list every `proposed` decision across all files (see the last row below). The `#DM` suffix is split off and handed back per that doc; decision = `DM`. Both `ADR-NNNN` and legacy `DEC-NNNN` references are accepted (the number selects the file, per that doc).
|
|
27
|
+
|
|
28
|
+
Then select the decision:
|
|
29
|
+
|
|
26
30
|
| Input | Resolution |
|
|
27
31
|
|-------|------------|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
| same, **multiple** proposed | list them, `AskUserQuestion` to pick |
|
|
33
|
-
| Empty/missing | list every `proposed` decision across all files (one row per `DEC-NNNN#DM`), ask user |
|
|
32
|
+
| `#DM` given | decision = `DM` |
|
|
33
|
+
| No `#DM`, file has **one** proposed decision | auto-resolve to it |
|
|
34
|
+
| No `#DM`, file has **multiple** proposed | list them, `AskUserQuestion` to pick |
|
|
35
|
+
| Empty/missing | list every `proposed` decision across all files (one row per `ADR-NNNN#DM`, or the file's own legacy `DEC-NNNN#DM` ID), ask user |
|
|
34
36
|
|
|
35
37
|
Can't locate file or decision → **stop and report**; never invent or create.
|
|
36
38
|
|
|
37
39
|
## Step 2: Read and audit the target block
|
|
38
40
|
|
|
39
41
|
1. `Read` the file; locate the `## DM. <title>` H2 and everything to the next `## D*` or EOF.
|
|
40
|
-
2. **Verify status is `proposed`:** `accepted` → stop (immutable; suggest `/
|
|
42
|
+
2. **Verify status is `proposed`:** `accepted` → stop (immutable; suggest `/adr-create` successor). `deprecated`/`superseded by …` → stop (no longer authoritative). To withdraw an accepted decision with no successor, use `/adr-deprecate`.
|
|
41
43
|
3. **Audit the target block only** (siblings out of scope) for unresolved content:
|
|
42
44
|
|
|
43
45
|
| Gap | Detection |
|
|
@@ -71,7 +73,7 @@ The rule operates **per decision, across every file**. Procedure:
|
|
|
71
73
|
| One candidate, all signals strong | `AskUserQuestion`, default "supersede this candidate" |
|
|
72
74
|
| Multiple | ranked list; user picks at most one |
|
|
73
75
|
| Candidate is `proposed` | skip (only `accepted` can be superseded); flag two-proposed-in-area as a consolidation hint |
|
|
74
|
-
| Candidate already `superseded by DEC-X#DY` | walk the chain to
|
|
76
|
+
| Candidate already `superseded by ADR-X#DY` (or legacy `DEC-X#DY`) | walk the chain to that target (the area's head) and supersede that instead |
|
|
75
77
|
| User declares "different area" despite signals | honor it; recommend revising target's tags to keep detection clean |
|
|
76
78
|
|
|
77
79
|
Persist the supersession target (or explicit "none") for Step 4. Do NOT proceed without resolving this.
|
|
@@ -85,15 +87,15 @@ Persist the supersession target (or explicit "none") for Step 4. Do NOT proceed
|
|
|
85
87
|
|
|
86
88
|
## Step 4: Apply edits to the target block
|
|
87
89
|
|
|
88
|
-
|
|
90
|
+
Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene. **Touch only the target block; siblings are inviolate.** Order:
|
|
89
91
|
1. Fill resolved content — each placeholder/empty row/TBD → user's confirmed answer; one `Edit` per distinct old_string, constrained to the target block via unique surrounding text.
|
|
90
92
|
2. Bold the chosen option in `### Decision Outcome`.
|
|
91
93
|
3. Convert any bullet-list comparisons to tables (within this block).
|
|
92
94
|
4. Add the mermaid diagram if flagged missing.
|
|
93
|
-
5. Update metadata: `Status` → `accepted`; `Date` → today (overwrite if blank/wrong, preserve if user wants original); `Deciders` → confirmed; `Tags` → confirmed non-empty; `Supersedes` → `
|
|
94
|
-
6. **If Step 2.5 named a supersession target**, apply the two-block cross-reference rule **atomically** (both change or neither); target may be in the same or a different file:
|
|
95
|
-
- **This decision (superseder):** `Supersedes:
|
|
96
|
-
- **Superseded block:** flip `Status: accepted` → `Status: superseded by
|
|
95
|
+
5. Update metadata: `Status` → `accepted`; `Date` → today (overwrite if blank/wrong, preserve if user wants original); `Deciders` → confirmed; `Tags` → confirmed non-empty; `Supersedes` → `ADR-MMMM#DK` or `none` (a legacy target keeps its own `DEC-MMMM#DK` ID as it appears in its file).
|
|
96
|
+
6. **If Step 2.5 named a supersession target**, apply the two-block cross-reference rule **atomically** (both change or neither); target may be in the same or a different file, and is edited in place wherever that file lives (never moved):
|
|
97
|
+
- **This decision (superseder):** `Supersedes: ADR-MMMM#DK` in metadata; `### Links` lists `Supersedes [[MMMM-slug\|ADR-MMMM#DK: title]]`.
|
|
98
|
+
- **Superseded block:** flip `Status: accepted` → `Status: superseded by ADR-NNNN#DX`; insert callout `> **Superseded by [[NNNN-slug\|ADR-NNNN#DX: title]]** on YYYY-MM-DD` directly **under that decision's H2** (not the file H1), between the H2 and its metadata bullets so a reader sees it first.
|
|
97
99
|
- **Superseded decision's siblings:** untouched.
|
|
98
100
|
7. Update `Last updated` in the file front matter to today — the only file-level edit.
|
|
99
101
|
|
|
@@ -117,39 +119,38 @@ Any failure → return to the relevant step. **Do not flip to `accepted` while g
|
|
|
117
119
|
|
|
118
120
|
## Step 6: Update index and relationship graph (`wiki/work/decisions/lifecycle.md`)
|
|
119
121
|
|
|
120
|
-
1. **Index — target row:** `Status` → `accepted`; `Date` → today; `Supersedes` → `[[MMMM-slug\|
|
|
121
|
-
2. **Index — superseded row (if any):** `Status` → `superseded by
|
|
122
|
-
3. **Relationship Graph** (mermaid `flowchart`): add a node for `
|
|
122
|
+
1. **Index — target row:** `Status` → `accepted`; `Date` → today; `Supersedes` → `[[MMMM-slug\|ADR-MMMM#DK: title]]` if named else `—`; `Superseded By` → `—`.
|
|
123
|
+
2. **Index — superseded row (if any):** `Status` → `superseded by ADR-NNNN#DX`; `Superseded By` → `[[NNNN-slug\|ADR-NNNN#DX: title]]`.
|
|
124
|
+
3. **Relationship Graph** (mermaid `flowchart`): add a node for `ADR-NNNN#DM` (title + date); if superseding, add an edge superseded→new labelled `superseded by` with date; update `class` lines (new → `accepted`, superseded → `superseded`); if still placeholder, replace with a real graph for the chain; subgraphs may group per file or per area.
|
|
125
|
+
|
|
126
|
+
If `lifecycle.md` doesn't exist, create it from the template under `/adr-create` Step 6. **Verify all three sections agree** before saving (index saying `superseded` while the graph shows the node `accepted` is a broken commit).
|
|
123
127
|
|
|
124
|
-
|
|
128
|
+
## Step 6.5: Family index: Closed if fully terminal
|
|
125
129
|
|
|
126
|
-
|
|
130
|
+
A group sits under `## Active` in `wiki/work/decisions/index.md` only while ≥1 block is `proposed`.
|
|
131
|
+
- Proposed blocks remain → update the row's per-decision note (e.g. `D1 accepted, D2 proposed`); leave the row under `## Active`.
|
|
132
|
+
- No proposed blocks remain (all `accepted`/`deprecated`/`superseded`) → follow `~/.claude/skills/_shared/ARCHIVE-WORK-ITEM.md` § In-place close (roadmaps, decisions, requirements) with `family: decisions`: move the group's row from `## Active` to `## Closed`, with the per-block summary (e.g. `D1 accepted, D2 superseded`) as the trailing segment. The file stays where it is — no `git mv`, no `archive/index.md` row. Step 7 writes the log entry, so pass `log: skip`.
|
|
127
133
|
|
|
128
|
-
|
|
129
|
-
- Proposed blocks remain → update the row's per-decision note (e.g. `D1 accepted, D2 proposed`); don't move the file.
|
|
130
|
-
- No proposed blocks remain (all `accepted`/`superseded`):
|
|
131
|
-
1. Delete the group's row from `index.md`.
|
|
132
|
-
2. `git mv wiki/work/decisions/<file>.md wiki/work/decisions/archive/<file>.md` (Bash — `git mv` only).
|
|
133
|
-
3. Append to `wiki/work/decisions/archive/index.md` (dominant final status — `accepted` unless all `superseded`): `| [[DEC-NNNN]] | <Title> | accepted | YYYY-MM-DD |`.
|
|
134
|
+
The file is never moved: a cross-group `superseded` flip (Step 4.6) edits the superseded block in place wherever its file lives, and a Closed group whose block gets superseded simply stays Closed.
|
|
134
135
|
|
|
135
|
-
`Read` then `Edit` for all index edits
|
|
136
|
+
`Read` then `Edit` for all index edits.
|
|
136
137
|
|
|
137
|
-
## Step 7: Append log entry (`wiki/log.md`, `Edit`
|
|
138
|
-
- No supersession: `## [YYYY-MM-DD]
|
|
139
|
-
- Supersession: `## [YYYY-MM-DD]
|
|
138
|
+
## Step 7: Append log entry (`wiki/log.md`, `Edit` only)
|
|
139
|
+
- No supersession: `## [YYYY-MM-DD] adr-accepted | ADR-NNNN#DM <Decision Title>`
|
|
140
|
+
- Supersession: `## [YYYY-MM-DD] adr-superseded | ADR-MMMM#DK superseded by ADR-NNNN#DM`
|
|
140
141
|
|
|
141
142
|
## Step 8: Cross-link follow-up work
|
|
142
143
|
|
|
143
144
|
Scan `### Consequences` for `🔁 Follow-up` rows (suggest only, never auto-create):
|
|
144
145
|
| Type | Suggestion |
|
|
145
146
|
|------|-----------|
|
|
146
|
-
| Implementation ("write task: …") | `/task-
|
|
147
|
+
| Implementation ("write task: …") | `/task-create <desc referencing ADR-NNNN#DM>` |
|
|
147
148
|
| Time-based revisit ("revisit in 6 months") | offer `/schedule` for the revisit date |
|
|
148
|
-
| Metric to instrument | `/task-
|
|
149
|
+
| Metric to instrument | `/task-create` or fold into an existing task — ask the user |
|
|
149
150
|
|
|
150
151
|
## Step 9: Update memory if a new pattern emerges
|
|
151
152
|
|
|
152
|
-
If the accepted decision creates a non-obvious pattern, integration constraint, or gotcha: `mcp__serena__write_memory` (topic-hierarchical name, e.g. `architecture/data-layer/cache-strategy`), referencing `
|
|
153
|
+
If the accepted decision creates a non-obvious pattern, integration constraint, or gotcha: `mcp__serena__write_memory` (topic-hierarchical name, e.g. `architecture/data-layer/cache-strategy`), referencing `ADR-NNNN#DM` not just the file; prefer `edit_memory` if a memory already covers the area.
|
|
153
154
|
|
|
154
155
|
## Step 10: Refresh the hot cache
|
|
155
156
|
|
|
@@ -157,7 +158,7 @@ Accepting a decision is durable, cross-session-relevant wiki state. Run the **Ho
|
|
|
157
158
|
|
|
158
159
|
## Step 11: Report
|
|
159
160
|
|
|
160
|
-
Table: Decision (`
|
|
161
|
+
Table: Decision (`ADR-NNNN#DM`), File, Old→New status (`proposed → accepted`), Gaps resolved (count), Format fixes (count), Supersession (`ADR-MMMM#DK` or `none`), Sibling decisions + status (unchanged), Index updated, Graph updated, Log appended, Suggested next steps (`/task-create …`, `/schedule …`, `/adr-finalize <file>#Dother`, `/adr-next`). Mention remaining proposed siblings. If the group is now fully terminal, note the group moved to Closed (Step 6.5) — the file itself does not move, so `[[ADR-NNNN]]` cross-refs stay valid.
|
|
161
162
|
|
|
162
163
|
---
|
|
163
164
|
|
|
@@ -165,7 +166,7 @@ Table: Decision (`DEC-NNNN#DM`), File, Old→New status (`proposed → accepted`
|
|
|
165
166
|
|
|
166
167
|
1. **Tables not bullets** — every comparison and audit summary, in output and edits.
|
|
167
168
|
2. **One Edit per gap** — surgical; don't rewrite whole blocks for one placeholder.
|
|
168
|
-
3. **Never alter accepted decisions** — refuse an already-accepted target; suggest `/
|
|
169
|
+
3. **Never alter accepted decisions** — refuse an already-accepted target; suggest `/adr-create`.
|
|
169
170
|
4. **Never touch sibling decisions** — only the target (plus the superseded block if applicable).
|
|
170
171
|
5. **Present tense, full sentences** when filling content.
|
|
171
172
|
6. **No fabrication** — if the user lacks an answer (e.g. concrete validation thresholds), keep `proposed`, mark the section honestly, and report remaining gaps.
|
|
@@ -176,6 +177,5 @@ Table: Decision (`DEC-NNNN#DM`), File, Old→New status (`proposed → accepted`
|
|
|
176
177
|
2. **Supersession is atomic and bidirectional** — new block, superseded block, index, and graph all change together or none do.
|
|
177
178
|
3. **Per-decision scope** — only the target block; siblings byte-for-byte unchanged at the end.
|
|
178
179
|
4. **No parallel `accepted` in the same area** — the chain invariant; if you can't resolve which supersedes which, leave `proposed` and report.
|
|
179
|
-
5. **Never
|
|
180
|
-
6. **
|
|
181
|
-
7. **Max 3 sub-processes at a time** if delegating; **always terminate processes when done**.
|
|
180
|
+
5. **Never auto-create tasks or schedules** — suggest them.
|
|
181
|
+
6. **Max 3 sub-processes at a time** if delegating; **always terminate processes when done**.
|