@codewizard-dt/bootstrap 2.10.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/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: req-retire
|
|
3
|
+
description: Retire a requirement — set status to retired in frontmatter, document the reason, move to archive/, append a log entry.
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-haiku-4-5-20251001
|
|
6
|
+
argument-hint: <wiki/work/requirements/REQ-NNN-slug.md, NNN-slug, or NNN> [reason]
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
**Read `wiki/work/requirements/lifecycle.md` first** — it defines the requirement lifecycle, terminal states, and the archive rule.
|
|
12
|
+
|
|
13
|
+
# Retire Requirement
|
|
14
|
+
|
|
15
|
+
Set a requirement's `status` to `retired`, document why, then move the file to `wiki/work/requirements/archive/`. After archiving, cross-references using `[[REQ-NNN]]` remain valid — the ID is stable regardless of file location.
|
|
16
|
+
|
|
17
|
+
This skill is a focused shortcut for the retirement flow. For amendments that don't touch status, use `/req-update`. For supersession (a new requirement replaces this one), use `/req-update` with supersession intent or pass `status: superseded` instructions here.
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
**Requirement**: $ARGUMENTS
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Instructions
|
|
28
|
+
|
|
29
|
+
### Step 1: Resolve the requirement file
|
|
30
|
+
|
|
31
|
+
Parse `$ARGUMENTS`:
|
|
32
|
+
- **First token(s)** — the file reference: `<path>`, `<NNN-slug>`, or `<NNN>`
|
|
33
|
+
- **Remaining text** — optional reason for retirement (may be elicited in Step 3 if absent)
|
|
34
|
+
|
|
35
|
+
| Input form | Resolution |
|
|
36
|
+
|------------|------------|
|
|
37
|
+
| `<path>` (e.g. `wiki/work/requirements/REQ-003-search.md`) | Use as-is; verify exists via `mcp__serena__find_file` |
|
|
38
|
+
| `<NNN-slug>` (e.g. `003-search`) | `mcp__serena__find_file` with mask `003-search.md` under `wiki/work/requirements/` |
|
|
39
|
+
| `<NNN>` (e.g. `3` or `003`) | Pad to 3 digits; `mcp__serena__find_file` with mask `NNN-*.md` under `wiki/work/requirements/` |
|
|
40
|
+
| Empty / missing | List every requirement in `wiki/work/requirements/` and ask the user via `AskUserQuestion` to pick |
|
|
41
|
+
|
|
42
|
+
If the file cannot be located, **stop** and report.
|
|
43
|
+
|
|
44
|
+
### Step 2: Read the requirement and verify status
|
|
45
|
+
|
|
46
|
+
1. **Read** the requirement file with `Read`.
|
|
47
|
+
2. **Check `status:` in frontmatter:**
|
|
48
|
+
|
|
49
|
+
| Current status | Action |
|
|
50
|
+
|----------------|--------|
|
|
51
|
+
| `draft` | Continue — may be retired before approval |
|
|
52
|
+
| `approved` | Continue — most common case |
|
|
53
|
+
| `retired` | **STOP.** Tell the user: "REQ-NNN is already retired. No action needed." |
|
|
54
|
+
| `superseded` | **STOP.** Tell the user: "REQ-NNN is already superseded. No action needed." |
|
|
55
|
+
|
|
56
|
+
3. **Check for downstream artifacts** in `## Linked Decisions` and `## Linked Tasks`:
|
|
57
|
+
- List any linked decisions and their current status
|
|
58
|
+
- List any linked tasks and their current status
|
|
59
|
+
- Build a downstream artifacts table for Step 3
|
|
60
|
+
|
|
61
|
+
### Step 3: Confirm with the user
|
|
62
|
+
|
|
63
|
+
Use `AskUserQuestion` to confirm. Show:
|
|
64
|
+
|
|
65
|
+
- The requirement file to be retired (full path, ID, title)
|
|
66
|
+
- Current status
|
|
67
|
+
- Downstream artifacts table (if any linked decisions or tasks exist):
|
|
68
|
+
|
|
69
|
+
| Artifact | Type | Current status | Suggested action |
|
|
70
|
+
|----------|------|----------------|------------------|
|
|
71
|
+
| `[[0007-auth\|DEC-0007#D2]]` | linked decision | accepted | Review independently — accepted decisions are immutable; if no longer needed, write a deprecating successor |
|
|
72
|
+
| `[[004-billing\|TASK-004]]` | linked task | todo | Run `/task-trash wiki/work/tasks/TASK-004-billing.md` if the task is also cancelled |
|
|
73
|
+
|
|
74
|
+
Ask the user:
|
|
75
|
+
|
|
76
|
+
1. **"Retire this requirement? (yes / no)"**
|
|
77
|
+
2. **"Reason for retiring REQ-NNN?"** (if not provided in `$ARGUMENTS` — required, one line or more)
|
|
78
|
+
|
|
79
|
+
If the user says **No**, STOP. Do not proceed.
|
|
80
|
+
|
|
81
|
+
**Do NOT ask whether to retire linked decisions or tasks** — they are surfaced as suggestions only. This skill never auto-cascades.
|
|
82
|
+
|
|
83
|
+
### Step 4: Apply the retirement edits
|
|
84
|
+
|
|
85
|
+
Use `Edit` for all changes — never `sed`, `awk`, `echo >>`, `cat <<EOF`, or `Write` for a full-file rewrite.
|
|
86
|
+
|
|
87
|
+
Apply in this order:
|
|
88
|
+
|
|
89
|
+
1. **Update `status: <current>` → `status: retired`** in frontmatter.
|
|
90
|
+
2. **Update `updated: YYYY-MM-DD`** in frontmatter to today's date.
|
|
91
|
+
3. **Append the retirement reason to `## Notes`**:
|
|
92
|
+
- If `## Notes` already has content, append a new paragraph.
|
|
93
|
+
- If `## Notes` is empty or has only a placeholder, replace the placeholder with the retirement entry:
|
|
94
|
+
```
|
|
95
|
+
**Retired [YYYY-MM-DD]**: <reason provided by user>
|
|
96
|
+
```
|
|
97
|
+
- If the `## Notes` section does not exist, add it at the end of the file.
|
|
98
|
+
|
|
99
|
+
### Step 5: Remove from the family index
|
|
100
|
+
|
|
101
|
+
`retired` is a terminal status — **delete the requirement's row** from `wiki/work/requirements/index.md` (the family index lists active items only).
|
|
102
|
+
|
|
103
|
+
Use `Read` then `Edit` — never `echo >>` or `sed`. If the row is already absent, note it and continue.
|
|
104
|
+
|
|
105
|
+
### Step 5.5: Archive the file
|
|
106
|
+
|
|
107
|
+
Move the file to `archive/` (Bash — `git mv` only):
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
git mv wiki/work/requirements/<file>.md wiki/work/requirements/archive/<file>.md
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Then append to `wiki/work/requirements/archive/index.md`:
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
| [[REQ-NNN]] | <Title> | retired | YYYY-MM-DD |
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Use `Read` then `Edit` for the archive index append — never `echo >>`.
|
|
120
|
+
|
|
121
|
+
### Step 6: Append to wiki/log.md
|
|
122
|
+
|
|
123
|
+
Append one entry to `wiki/log.md`:
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
## [YYYY-MM-DD] req-retired | REQ-NNN <title> — reason: <one-line summary of reason>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Use `Read` then `Edit` — never `echo >>` or `sed`.
|
|
130
|
+
|
|
131
|
+
### Step 7: Surface downstream artifacts for independent action
|
|
132
|
+
|
|
133
|
+
Print the downstream artifacts table from Step 3 again, with suggested next-action commands:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
Linked decisions and tasks surfaced for independent review:
|
|
137
|
+
|
|
138
|
+
To act on linked tasks (each independently):
|
|
139
|
+
/task-trash wiki/work/tasks/TASK-004-billing.md # if task is also cancelled
|
|
140
|
+
|
|
141
|
+
To act on linked decisions (each independently):
|
|
142
|
+
# Accepted decisions are immutable — write a deprecating successor:
|
|
143
|
+
/decision-create deprecate <topic> (supersedes DEC-0007#D2)
|
|
144
|
+
# Proposed decisions may be left, finalized, or abandoned
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Step 8: Report completion
|
|
148
|
+
|
|
149
|
+
Print a tabular summary:
|
|
150
|
+
|
|
151
|
+
| Field | Value |
|
|
152
|
+
|-------|-------|
|
|
153
|
+
| Requirement | `REQ-NNN <title>` |
|
|
154
|
+
| File path | `wiki/work/requirements/REQ-NNN-slug.md` → `wiki/work/requirements/archive/REQ-NNN-slug.md` |
|
|
155
|
+
| Old status | `draft` or `approved` |
|
|
156
|
+
| New status | `retired` |
|
|
157
|
+
| Reason | <one-line summary> |
|
|
158
|
+
| Family index updated | yes (row removed — terminal status) |
|
|
159
|
+
| Archive index updated | yes (row appended) |
|
|
160
|
+
| wiki/log.md entry | yes |
|
|
161
|
+
| Linked decisions surfaced | count |
|
|
162
|
+
| Linked tasks surfaced | count |
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Output Formatting Rules
|
|
167
|
+
|
|
168
|
+
1. Use tables for the downstream artifacts list and the completion report — never paragraph prose.
|
|
169
|
+
2. **One `Edit` call per change** — never bulk rewrites.
|
|
170
|
+
3. **After archiving, cross-references using `[[REQ-NNN]]` remain valid** — the ID is stable regardless of file location.
|
|
171
|
+
4. **The skill never auto-retires or auto-deprecates downstream artifacts** — it surfaces them with suggested commands.
|
|
172
|
+
5. **The retirement reason in `## Notes` is permanent** — it is the audit trail for why this requirement was retired.
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## CRITICAL Rules
|
|
177
|
+
|
|
178
|
+
1. **Archiving (not deletion) is the terminal action.** Set `status: retired` in frontmatter AND move the file to `wiki/work/requirements/archive/` via `git mv`.
|
|
179
|
+
2. **Never auto-cascade** to linked decisions or tasks. Surface them as suggestions only.
|
|
180
|
+
3. **Confirm with the user before any edits** — `AskUserQuestion` is mandatory in Step 3.
|
|
181
|
+
4. **Retirement reason is required** — refuse to retire without a documented reason.
|
|
182
|
+
5. **Never use `sed` / `awk` / `echo >>` / `cat <<EOF`** — always `Edit`. `Bash` is permitted only for `git mv`. See `.docs/guides/mcp-tools.md`.
|
|
183
|
+
6. **Refuse if already retired or superseded** — these are terminal states; running again is a no-op, not an error.
|
|
184
|
+
7. Maximum 3 sub-processes at a time if delegating any step.
|
|
185
|
+
8. Always terminate background processes when done.
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: req-update
|
|
3
|
+
description: Amend an approved requirement with a tracked Amendment block (append-only); apply direct edits to drafts; set retired/superseded status; surface downstream decision/task impact
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: <path/to/req.md, NNN-slug, or NNN> [optional change description]
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
# Update Requirement
|
|
13
|
+
|
|
14
|
+
Amend an existing requirement with a change. The mechanics depend on the requirement's status:
|
|
15
|
+
|
|
16
|
+
| Requirement Status | Behavior |
|
|
17
|
+
|--------------------|----------|
|
|
18
|
+
| `draft` | Apply edits directly in place — drafts are mutable |
|
|
19
|
+
| `approved` | Append an `## Amendment N` block; insert surgical `[amended N]` markers in affected sections; **never rewrite original prose** |
|
|
20
|
+
| `approved` (retiring) | Set `status: retired`, append reason to `## Notes`, update wiki index, append log entry — use `/req-retire` for a dedicated retirement flow |
|
|
21
|
+
| `retired` / `superseded` | Refuse general amendments — these requirements are no longer authoritative; suggest `/req-create` for new scope |
|
|
22
|
+
|
|
23
|
+
**Approved requirements are immutable in substance.** The amendment block is the audit trail. Original sections stay readable in their original form; markers point readers to the amendment that updated them. Amendments are themselves immutable once written — never edit a prior amendment block; append a new one.
|
|
24
|
+
|
|
25
|
+
**Check `wiki/work/requirements/lifecycle.md` first.** It defines the requirement format and status lifecycle; the `## Amendments` convention and the "Amendment Avoidance" anti-pattern this skill exists to prevent live there and in recent REQ files.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
**Input**: $ARGUMENTS
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Step 1: Resolve the requirement file and parse change instructions
|
|
34
|
+
|
|
35
|
+
Parse `$ARGUMENTS`:
|
|
36
|
+
- **First token** — the file reference: `<path>`, `<NNN-slug>`, or `<NNN>`
|
|
37
|
+
- **Remaining text** — free-form change instructions describing what the user wants to amend
|
|
38
|
+
|
|
39
|
+
Resolution table:
|
|
40
|
+
|
|
41
|
+
| Input form | Resolution |
|
|
42
|
+
|------------|------------|
|
|
43
|
+
| `<path>` (e.g. `wiki/work/requirements/REQ-003-billing-portal.md`) | Use as-is |
|
|
44
|
+
| `<NNN-slug>` (e.g. `003-billing-portal`) | Search `wiki/work/requirements/` for `<NNN-slug>.md` (Serena `find_file`) |
|
|
45
|
+
| `<NNN>` (e.g. `3` or `003`) | Pad to 3 digits; search `wiki/work/requirements/` for files starting with that number; if ambiguous, list matches and ask the user via `AskUserQuestion` |
|
|
46
|
+
| Empty | List every requirement in `wiki/work/requirements/` and ask the user via `AskUserQuestion` to pick |
|
|
47
|
+
|
|
48
|
+
If the file cannot be located, **stop** and report — do not invent or create.
|
|
49
|
+
|
|
50
|
+
If the **change instructions are empty**, use `AskUserQuestion` to elicit them before proceeding. A `/req-update` invocation without a described change is malformed.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Step 2: Read the requirement and check status
|
|
55
|
+
|
|
56
|
+
1. **Read** the requirement file with `Read`.
|
|
57
|
+
2. **Locate the `status:` field** in the YAML frontmatter.
|
|
58
|
+
3. **Branch on status:**
|
|
59
|
+
|
|
60
|
+
| Status | Action |
|
|
61
|
+
|--------|--------|
|
|
62
|
+
| `draft` | Continue to Step 3 (you will take the **direct-edit branch** in Step 4) |
|
|
63
|
+
| `approved` | Continue to Step 3 (you will take the **amendment branch** in Step 4); also check if the user intends to retire (see retiring branch below) |
|
|
64
|
+
| `retired` | **STOP.** Tell the user: "REQ-NNN is retired. Run `/req-create` for any new scope." |
|
|
65
|
+
| `superseded` | **STOP.** Tell the user: "REQ-NNN was superseded. Update the successor requirement instead." |
|
|
66
|
+
|
|
67
|
+
**Retiring branch** (when the user indicates they want to mark the requirement as retired):
|
|
68
|
+
1. Ask for the retirement reason via `AskUserQuestion`
|
|
69
|
+
2. Set `status: retired` in frontmatter
|
|
70
|
+
3. Append reason to `## Notes` section: *"Retired YYYY-MM-DD: <reason>"*
|
|
71
|
+
4. Update `updated` in frontmatter to today's date
|
|
72
|
+
5. Remove the requirement's row from `wiki/work/requirements/index.md` (terminal status — active index only)
|
|
73
|
+
6. Append to `wiki/log.md`: `## [YYYY-MM-DD] req-retired | REQ-NNN <title> — <reason>`
|
|
74
|
+
7. Skip to Step 10 (report)
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Step 3: Determine change scope and impact
|
|
79
|
+
|
|
80
|
+
Before any edit is applied, fully characterize the change. Use `AskUserQuestion` to gather (in this order):
|
|
81
|
+
|
|
82
|
+
1. **Affected sections** — which requirement sections does this change touch?
|
|
83
|
+
|
|
84
|
+
| Candidate section | Typical reason for amendment |
|
|
85
|
+
|-------------------|------------------------------|
|
|
86
|
+
| Problem Statement | New evidence reframes the problem |
|
|
87
|
+
| Goals | A goal added, removed, or rephrased |
|
|
88
|
+
| Non-Goals | Scope tightened or loosened |
|
|
89
|
+
| Personas | New persona discovered or one removed |
|
|
90
|
+
| User Stories | Story added, removed, or acceptance criteria changed |
|
|
91
|
+
| Success Metrics | Threshold or signal updated |
|
|
92
|
+
| Constraints | New regulatory or business constraint |
|
|
93
|
+
| Assumptions | Assumption invalidated |
|
|
94
|
+
| Open Questions | Resolution arrived |
|
|
95
|
+
| stakeholders | Reviewer set changed |
|
|
96
|
+
|
|
97
|
+
2. **Reason category** — pick one:
|
|
98
|
+
|
|
99
|
+
| Category | When applicable |
|
|
100
|
+
|----------|-----------------|
|
|
101
|
+
| `new evidence` | User research, support tickets, or analytics changed the picture |
|
|
102
|
+
| `scope clarification` | Original wording was ambiguous; this nails it down |
|
|
103
|
+
| `stakeholder request` | A named stakeholder asked for the change |
|
|
104
|
+
| `external constraint` | Legal, compliance, vendor change |
|
|
105
|
+
| `discovered ambiguity` | Implementation revealed an unanswered question |
|
|
106
|
+
|
|
107
|
+
3. **Downstream impact** — read the requirement's `## Linked Decisions` and `## Linked Tasks` tables.
|
|
108
|
+
- **If linked decisions exist:** list them and ask whether the change might invalidate any decision
|
|
109
|
+
- **If linked tasks exist:** list them and ask whether the change affects their scope
|
|
110
|
+
- If neither table has rows, skip — but still surface "no downstream artifacts" in the Step 10 report
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Step 4: Branch on status
|
|
115
|
+
|
|
116
|
+
### Branch A — `draft` requirement (direct-edit, mutable)
|
|
117
|
+
|
|
118
|
+
1. **Apply each distinct change with one `Edit` call.** Never bulk-rewrite.
|
|
119
|
+
2. **Update `updated`** in frontmatter to today's date.
|
|
120
|
+
3. If the change involves **adding or removing user stories, success metrics, or non-goals**, surface a one-line reminder: *"This requirement is still `draft`. When you're ready to approve, run `/req-finalize <path>` to re-audit completeness."*
|
|
121
|
+
4. **Skip Steps 5–8.** Proceed directly to Step 9 (downstream impact) and Step 10 (report).
|
|
122
|
+
|
|
123
|
+
### Branch B — `approved` requirement (amendment-only, append-only)
|
|
124
|
+
|
|
125
|
+
Approved requirements are immutable in substance. The original sections are not rewritten; instead:
|
|
126
|
+
|
|
127
|
+
- A new `## Amendment N` block is appended under the file's `## Amendments` heading
|
|
128
|
+
- Surgical `[amended N]` markers are inserted in the affected sections pointing to the amendment block
|
|
129
|
+
- The original prose stays readable in its original form
|
|
130
|
+
|
|
131
|
+
Determine **N**:
|
|
132
|
+
|
|
133
|
+
1. Scan the requirement for existing `## Amendment N` H2 blocks
|
|
134
|
+
2. `N` = (highest existing amendment number) + 1, or `1` if none exist
|
|
135
|
+
|
|
136
|
+
Continue to Step 5.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Step 5: Compose the amendment block (approved-requirement branch only)
|
|
141
|
+
|
|
142
|
+
Draft the amendment block in your working context. Format:
|
|
143
|
+
|
|
144
|
+
```markdown
|
|
145
|
+
## Amendment N (YYYY-MM-DD)
|
|
146
|
+
|
|
147
|
+
- **Reason**: <reason category from Step 3>
|
|
148
|
+
- **Affected sections**: <comma-separated list from Step 3>
|
|
149
|
+
- **Stakeholders consulted**: <names or roles>
|
|
150
|
+
- **Downstream impact**: <decision/task IDs that may need review, or "none">
|
|
151
|
+
|
|
152
|
+
### Changes
|
|
153
|
+
|
|
154
|
+
| Section | Before (summary) | After (summary) | Rationale |
|
|
155
|
+
|---------|------------------|-----------------|-----------|
|
|
156
|
+
| Problem Statement | <one-line summary of original> | <one-line summary of amended> | <why> |
|
|
157
|
+
|
|
158
|
+
### Detailed Diff (optional)
|
|
159
|
+
|
|
160
|
+
<Free-form prose for the substance of the change.>
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Rules:
|
|
164
|
+
- One row in the `### Changes` table per affected section
|
|
165
|
+
- `### Detailed Diff` is optional but recommended when the substance is non-trivial
|
|
166
|
+
- Use today's date in the H2
|
|
167
|
+
|
|
168
|
+
**Confirm the amendment-block content with the user via `AskUserQuestion` before writing.** Amendments are append-only and themselves immutable.
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Step 6: Apply surgical `[amended N]` markers (approved-requirement branch only)
|
|
173
|
+
|
|
174
|
+
For each affected section in the original requirement body, insert an inline marker pointing to the new amendment. **Do not rewrite the original prose.**
|
|
175
|
+
|
|
176
|
+
Marker patterns by section type:
|
|
177
|
+
|
|
178
|
+
| Section type | Marker pattern |
|
|
179
|
+
|--------------|----------------|
|
|
180
|
+
| Table row | Append `[amended N — see below]` to the relevant cell |
|
|
181
|
+
| Prose paragraph | Append `_(See [Amendment N](#amendment-N-yyyy-mm-dd).)_` at end of paragraph |
|
|
182
|
+
| Bulleted/numbered list item | Append `[amended N]` to the line |
|
|
183
|
+
|
|
184
|
+
Apply each marker with one `Edit` call. Use unique surrounding text in `old_string`.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Step 7: Append the amendment block to the file (approved-requirement branch only)
|
|
189
|
+
|
|
190
|
+
1. **Read** the file again (state may have changed after Step 6's edits).
|
|
191
|
+
2. **Locate the `## Amendments` heading.**
|
|
192
|
+
- If the file still has the placeholder comment, append the new block beneath the comment
|
|
193
|
+
- If previous amendments exist, append the new block after the last existing `## Amendment` block
|
|
194
|
+
3. **Use `Edit`** to insert the block.
|
|
195
|
+
4. **Never** use `sed`, `echo >>`, `cat <<EOF`, or `Write` for a full-file rewrite. Only `Edit`.
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Step 8: Update `updated` and the wiki index
|
|
200
|
+
|
|
201
|
+
1. **Update the requirement's `updated` field** in frontmatter to today's date via `Edit`.
|
|
202
|
+
2. **Edit `wiki/work/requirements/index.md`** only if amendment-relevant columns changed (Title, Owner). Typically the index row stays stable for amendments.
|
|
203
|
+
|
|
204
|
+
Append to `wiki/log.md`:
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
## [YYYY-MM-DD] req-updated | REQ-NNN <title> — Amendment N
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## Step 9: Surface downstream impact
|
|
213
|
+
|
|
214
|
+
Print a tabular report listing every linked decision and linked task that might need review:
|
|
215
|
+
|
|
216
|
+
| Artifact | Type | Status | Suggested Action |
|
|
217
|
+
|----------|------|--------|------------------|
|
|
218
|
+
| `DEC-0007#D2` | linked decision | accepted | Review whether amendment invalidates the decision; if so, write a successor via `/decision-create` |
|
|
219
|
+
| `wiki/work/tasks/TASK-004-billing-checkout.md` | linked task | in-progress | Review whether amendment changes the task scope; if so, run `/task-update ...` |
|
|
220
|
+
|
|
221
|
+
If there are no linked artifacts, print: *"No downstream decisions or tasks linked. No further action."*
|
|
222
|
+
|
|
223
|
+
This skill **does not auto-update or auto-deprecate** downstream artifacts.
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Step 10: Report completion
|
|
228
|
+
|
|
229
|
+
Print a single tabular summary:
|
|
230
|
+
|
|
231
|
+
| Field | Value |
|
|
232
|
+
|-------|-------|
|
|
233
|
+
| File | `<path>` |
|
|
234
|
+
| Branch taken | `direct-edit (draft)`, `amendment (approved)`, or `retired` |
|
|
235
|
+
| Amendment number | `N` (or `—` for direct-edit/retired) |
|
|
236
|
+
| `[amended N]` markers added | count (or `—`) |
|
|
237
|
+
| Sections touched | comma-separated list |
|
|
238
|
+
| Downstream artifacts flagged | count |
|
|
239
|
+
| Log entry | appended to wiki/log.md |
|
|
240
|
+
| Suggested next steps | `/req-finalize ...` (drafts), `/task-update ...`, `/decision-create ...`, etc. |
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## Output Formatting Rules (mandatory)
|
|
245
|
+
|
|
246
|
+
1. **Tables not bullets** — the amendment block's `### Changes` section, the downstream-impact report, and the completion summary are all tables
|
|
247
|
+
2. **Approved requirements are append-only in substance** — original sections must remain readable; markers point to amendments, they do not replace text
|
|
248
|
+
3. **Surgical `Edit` calls** — one `Edit` per distinct change; never bulk rewrites
|
|
249
|
+
4. **Never use `sed`, `echo >>`, `cat <<EOF`** — always `Edit`
|
|
250
|
+
5. **Amendments are themselves immutable** once written — never edit a prior `## Amendment N` block
|
|
251
|
+
6. **Refuse general amendments on `retired` / `superseded` status** — suggest `/req-create` for new scope
|
|
252
|
+
7. **Confirm amendment-block content** with the user via `AskUserQuestion` before writing
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## CRITICAL Rules
|
|
257
|
+
|
|
258
|
+
1. **Approved requirements are immutable in substance** — appending amendments is the ONLY allowed change
|
|
259
|
+
2. **Original prose stays visible** — `[amended N]` markers point to amendments; they do not replace the original content
|
|
260
|
+
3. **Amendment blocks are themselves append-only** — never edit a prior amendment block
|
|
261
|
+
4. **Refuse on terminal statuses** (`retired`, `superseded`) — suggest `/req-create` for new scope
|
|
262
|
+
5. **Never auto-update downstream artifacts** — surface linked decisions and tasks for user review
|
|
263
|
+
6. **Never use `sed`/`echo >>`/`cat <<EOF`** — always `Edit`
|
|
264
|
+
7. **Maximum 3 sub-processes at a time** if delegating
|
|
265
|
+
8. **Always terminate processes when done**
|