@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,124 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: req-create
|
|
3
|
+
description: Draft a new requirement in wiki/work/requirements/ via Socratic Q&A capturing problem, personas, user stories, success metrics, and non-goals
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
effort: high
|
|
7
|
+
argument-hint: <feature description, problem statement, or product initiative title>
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
|
+
**Check `wiki/work/requirements/lifecycle.md`** for the REQ template, status lifecycle, required-non-empty fields, and anti-patterns this skill enforces; **`wiki/work/requirements/index.md`** for the index row format.
|
|
13
|
+
|
|
14
|
+
# Create Requirement
|
|
15
|
+
|
|
16
|
+
Create a **Requirement** (REQ) — **what to build and why** from a product perspective: problem, personas, desired outcomes, explicit non-goals. Requirements sit **upstream** of decisions and tasks; they define *what* and *why*, never *how*.
|
|
17
|
+
|
|
18
|
+
> *A requirement never justifies architecture. A decision never redefines product scope.* (Joel Parker Henderson's REQ↔Decision pattern)
|
|
19
|
+
|
|
20
|
+
If the user specifies file paths, libraries, schemas, or frameworks, **redirect** — that belongs in a downstream decision. This skill drives a **Socratic Q&A** via `AskUserQuestion`: it *interrogates* the user rather than guessing.
|
|
21
|
+
|
|
22
|
+
**Topic**: $ARGUMENTS
|
|
23
|
+
|
|
24
|
+
## When to write
|
|
25
|
+
|
|
26
|
+
Write when there's a real problem worth aligning on, more than one decision area, multiple stakeholders, and the *what* is not obvious from the codebase. For a bug fix, refactor, one-line config change, or a pure *how* question — **stop and tell the user**; suggest `/task-add` or `/decision-create`.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Step 1: Parse topic, recall context
|
|
31
|
+
1. Extract the topic from `$ARGUMENTS`; too vague ("search", "make it better", "auth") → `AskUserQuestion` to narrow first.
|
|
32
|
+
2. Recall memories: `list_memories`, `read_memory` for topic-relevant ones (personas, regulatory constraints, prior attempts, gotchas).
|
|
33
|
+
3. Read `CLAUDE.md`, `PROJECT_STATUS.md` (if present), `wiki/work/requirements/lifecycle.md` (authoritative template/lifecycle/anti-patterns), and a sample of recent requirements for local conventions.
|
|
34
|
+
|
|
35
|
+
## Step 2: Locate directory, assign number
|
|
36
|
+
Requirements live at `wiki/work/requirements/REQ-NNN-slug.md` (3-digit zero-padded). `list_dir` both `wiki/work/requirements/` and `wiki/work/requirements/archive/` (skip either that doesn't exist) — highest prefix across both + 1 (first is `REQ-001`). Never re-use a number; retired requirements keep theirs forever. Derive the slug — names the **initiative**, lowercase dash-separated ≤60 chars (e.g. "Self-serve billing portal" → `REQ-004-self-serve-billing-portal.md`). Confirm number + slug via `AskUserQuestion` if non-obvious.
|
|
37
|
+
|
|
38
|
+
## Step 3: Research (optional, scoped)
|
|
39
|
+
For an unfamiliar product space, run a **lightweight** `/research` for **product context only**:
|
|
40
|
+
|
|
41
|
+
| In scope | Out of scope (defer to decision/task) |
|
|
42
|
+
|----------|---------------------------------------|
|
|
43
|
+
| Competitive landscape · UX precedents · persona prior art · regulatory/compliance context · domain vocabulary | Library/framework choices · schema/API design · file paths/function names · tool benchmarks · implementation trade-offs |
|
|
44
|
+
|
|
45
|
+
Skip entirely for well-understood internal tooling, follow-ups in an established area, or when the user is the domain expert. Cap external lookups (Brave, Context7) to what's needed to ask informed Step 4 questions. **Never** write requirement fields from research output — every field comes from user-confirmed Step 4 input.
|
|
46
|
+
|
|
47
|
+
## Step 4: Socratic Q&A via `AskUserQuestion` (the heart of this skill)
|
|
48
|
+
Walk the elicitations **in order**. Batch related ones into a single round when feasible, but never collapse two distinct elicitations into one cell. Each answer must clear its **quality bar**; if it fails, ask follow-ups until it passes — never silently accept a weak answer or invent content.
|
|
49
|
+
|
|
50
|
+
| # | Elicitation | Quality bar | Reject & re-ask if |
|
|
51
|
+
|---|-------------|-------------|--------------------|
|
|
52
|
+
| 1 | **Problem Statement** | 2-4 sentences: what's broken/missing/possible and *why now* | "Make it better"; solution smuggled in ("add a Postgres index") |
|
|
53
|
+
| 2 | **Personas (≥1)** | Named individual or role with context (where they sit, constraints) + primary goal | "Users", "the team", "everyone" |
|
|
54
|
+
| 3 | **User Stories (≥1)** | *"As `<persona>`, I want `<capability>` so that `<outcome>`."* + an Acceptance Criteria table of observable, testable behaviors | No AC; AC as test code (`assert X = Y`); AC describing implementation |
|
|
55
|
+
| 4 | **Success Metrics (≥1)** | Each row: **signal + threshold + timeframe** (e.g. weekly active sessions, ≥1.5× baseline, 30 days post-launch) | "Improve X" / "make it faster" with no numbers |
|
|
56
|
+
| 5 | **Goals (≥1)** | Outcome-oriented sentence **linking a Success Metric ID** (`SM-1`, …) | Goal without a linked metric; restates an output not an outcome |
|
|
57
|
+
| 6 | **Non-Goals (≥1, mandatory)** | ≥1 explicit out-of-scope item with a *why excluded*. Ask: "What would a reader wrongly assume is in scope?" | "N/A", empty, "TBD" |
|
|
58
|
+
| 7 | **Constraints (may be empty)** | Each attributes a source: legal/regulatory/business/technical | Hand-waved "must be fast"; no source |
|
|
59
|
+
| 8 | **Assumptions (may be empty)** | Each carries an *if false, impact* column | Untracked/implicit assumptions |
|
|
60
|
+
| 9 | **Open Questions (may be empty)** | Each has an owner + target resolution date | Logged with no owner |
|
|
61
|
+
| 10 | **Owner + Stakeholders** | Single accountable Owner (one name/role) + named Stakeholders | "The team", "everyone", missing owner |
|
|
62
|
+
| 11 | **Tags (mandatory, 1-3)** | Short area tags (`auth`, `billing`, `search`) | Empty; over-broad single tag like `product` |
|
|
63
|
+
|
|
64
|
+
**Suggested batching:** (1) Problem, Personas · (2) User Stories+AC, Success Metrics · (3) Goals, Non-Goals, Constraints, Assumptions · (4) Owner, Stakeholders, Tags, Open Questions. Adjust as the conversation flows — the rule is *every elicitation passes its bar before Step 5*.
|
|
65
|
+
|
|
66
|
+
**Redirection rule:** if the user answers with implementation specifics (file paths, function names, libraries, schema fields), respond: *"That sounds like an architectural decision, not a product requirement. Let's keep this to what and why; how is captured later in a decision via `/decision-create` after `/req-finalize` and `/req-extract-decisions`."* Then re-ask for the user-visible behavior/outcome.
|
|
67
|
+
|
|
68
|
+
## Step 5: Preview and confirm before writing
|
|
69
|
+
Present a **tabular preview** of every elicited section; user confirms via `AskUserQuestion` (*Approve and write* / *Edit specific section* / *Cancel*). **Do not write until explicit approval.** Preview must include at least: Header (Title, status `draft`, Owner, Stakeholders, Tags), Problem Statement (full), Personas (table), User Stories (`US-N` titles + AC counts), Success Metrics (full table), Goals→Metrics (full table showing the link), Non-Goals (full table), Constraints/Assumptions/Open Questions (tables or "(empty — none elicited)"). Edits → loop back to the relevant Step 4 elicitation and re-present.
|
|
70
|
+
|
|
71
|
+
## Step 6: Write the file
|
|
72
|
+
After confirmation, `Write` `wiki/work/requirements/REQ-NNN-slug.md`.
|
|
73
|
+
|
|
74
|
+
```yaml
|
|
75
|
+
---
|
|
76
|
+
id: REQ-NNN
|
|
77
|
+
type: requirement
|
|
78
|
+
status: draft
|
|
79
|
+
created: YYYY-MM-DD
|
|
80
|
+
updated: YYYY-MM-DD
|
|
81
|
+
owner: <name or role>
|
|
82
|
+
stakeholders: [<name or role>, ...]
|
|
83
|
+
superseded-by: ""
|
|
84
|
+
tags: [<tag1>, <tag2>]
|
|
85
|
+
---
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Sections in order: `# REQ-NNN: <Title>` · `## Problem Statement` · `## Goals` (table, every row links a Success Metric ID) · `## Non-Goals` (≥1 row) · `## Personas` (table) · `## User Stories` (each `### US-N. <title>` with the story sentence + an AC table) · `## Success Metrics` (table) · `## Constraints` / `## Assumptions` / `## Open Questions` (table or "(none — placeholder retained)") · `## Linked Decisions` (empty, retain explanatory blockquote) · `## Linked Tasks` (empty, blockquote) · `## Notes` (empty) · `## Amendments` (empty, `<!-- Amendments appear here as ## Amendment 1, ## Amendment 2, etc. -->`).
|
|
89
|
+
|
|
90
|
+
**Refuse to write** if any required-non-empty field is missing or fails its bar — loop back to Step 4.
|
|
91
|
+
|
|
92
|
+
## Step 7: Update indexes + log (`Edit` only, never `sed`/`awk`/`echo >>`)
|
|
93
|
+
Update `wiki/work/requirements/index.md` — if the placeholder row `_No requirements yet …_` exists, **replace** it; else **append** in ascending REQ order. Row/columns: `ID` = `[REQ-NNN](../work/requirements/REQ-NNN-slug.md)` · `Title` · `Status` = `draft` · `Created` = `YYYY-MM-DD` · `Owner` · `Linked Decisions` = `—` · `Linked Tasks` = `—`. Append to `wiki/log.md`: `## [YYYY-MM-DD] req-create | REQ-NNN <title>`.
|
|
94
|
+
|
|
95
|
+
## Step 8: Cross-link related artifacts
|
|
96
|
+
If prompted by an existing task/research note/reference, link both ways (`Read` then `Edit`, never `sed`): source artifact gets `**Requirement**: REQ-NNN ([file](<relative-link>))` in a sensible section; the new requirement references the source in `## Notes` (e.g. "Originated from `wiki/work/tasks/TASK-012-runbook-triage.md`"). No related artifact → skip.
|
|
97
|
+
|
|
98
|
+
## Step 9: Update memory if appropriate
|
|
99
|
+
`mcp__serena__write_memory` only for a **non-obvious** product insight future sessions benefit from (a genuinely new persona; a regulatory constraint; a known product gotcha) — skip self-evident ones or conjecture. Topic-hierarchical name (`product/personas/sre-oncall`, `product/constraints/soc2-admin-logging`), referencing `REQ-NNN` in the body.
|
|
100
|
+
|
|
101
|
+
## Step 10: Report
|
|
102
|
+
Tabular summary: File path, Status (`draft`), Personas/User Stories/Success Metrics/Non-Goals counts, Constraints/Assumptions/Open Questions (populated/empty per section), index updated (1 row), log appended, cross-links (list or *none*), memory (name or *skipped*), suggested next step `/req-finalize wiki/work/requirements/REQ-NNN-slug.md`. Note any placeholder-reduced field under a **Gaps** section for the user to address before `/req-finalize`.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Output formatting rules (mandatory — override default style)
|
|
107
|
+
1. **Tables not bullets** for every comparison/enumeration (Goals→Metrics, Non-Goals, Personas, Acceptance Criteria, Success Metrics, Constraints, Assumptions, Open Questions).
|
|
108
|
+
2. **Present tense, full sentences** — "Casey discovers the runbook within 30 seconds of paging", not "discover runbook fast".
|
|
109
|
+
3. **Personas are named individuals or roles, never "users"** — "Casey, the on-call SRE" ✅.
|
|
110
|
+
4. **Every Goal links a Success Metric ID** — goals without `SM-N` are rejected and re-elicited.
|
|
111
|
+
5. **Every Success Metric has signal + threshold + timeframe** — "Improve X" is rejected.
|
|
112
|
+
6. **≥1 Non-Goal** — an empty `## Non-Goals` is a hard fail.
|
|
113
|
+
7. **No implementation specifics** — no file paths, function names, library choices, schema fragments, or API routes.
|
|
114
|
+
8. **Acceptance criteria describe observable user-visible behavior** — not test cases, assertions, or internal state checks.
|
|
115
|
+
|
|
116
|
+
## CRITICAL rules
|
|
117
|
+
1. **Max 3 sub-processes at a time** if delegating Step 3 research; **always terminate processes when done**.
|
|
118
|
+
2. **Refuse to write if any required-non-empty field is empty or fails its bar** — loop back to Step 4.
|
|
119
|
+
3. **Never invent personas, metrics, user stories, or non-goals** — every entry from user-confirmed `AskUserQuestion` input.
|
|
120
|
+
4. **Never `sed`/`awk`/`echo >>`/shell redirection to edit markdown** — always `Read` then `Edit`.
|
|
121
|
+
5. **Tags non-empty is mandatory** — refuse to write if Step 4 #11 yielded zero tags.
|
|
122
|
+
6. **Never auto-create downstream artifacts** — exactly one requirement file (+ index + log + cross-link edits); no decisions, tasks, or research notes as a side effect.
|
|
123
|
+
7. **Redirect implementation talk to decision territory** — restate as *what*/*why* and re-elicit.
|
|
124
|
+
8. **Two-domain rule** — requirements are stateful work artifacts under `wiki/work/requirements/`; never file under `wiki/knowledge/`.
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: req-extract-decisions
|
|
3
|
+
description: Extract Architecturally Significant Requirements from an approved requirement, cross-check existing decisions, and propose Decision Group candidates for /decision-create
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-opus-4-8
|
|
6
|
+
effort: high
|
|
7
|
+
argument-hint: <path/to/req.md, NNN-slug, or NNN>
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
# Requirement to Decisions
|
|
15
|
+
|
|
16
|
+
Bridge an **approved** requirement into the architectural decision pipeline. This skill walks the requirement, extracts **Architecturally Significant Requirements (ASRs)**, cross-checks them against the existing decision log, groups remaining ASRs into Decision Group candidates, and writes both sides of the bidirectional cross-link: placeholder rows in the requirement's `## Linked Decisions` table and `Source REQ:` back-links on any existing decision that already covers an ASR.
|
|
17
|
+
|
|
18
|
+
This skill **never** invokes `/decision-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 `## Linked Decisions` table format with wikilinks and the ASR taxonomy.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
**Target**: $ARGUMENTS
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Instructions
|
|
29
|
+
|
|
30
|
+
### Step 1: Resolve the requirement file
|
|
31
|
+
|
|
32
|
+
Parse `$ARGUMENTS` to identify the target:
|
|
33
|
+
|
|
34
|
+
| Input form | Resolution |
|
|
35
|
+
|------------|------------|
|
|
36
|
+
| `<path>` (e.g. `wiki/work/requirements/REQ-003-onboarding.md`) | Use as-is; verify the file exists |
|
|
37
|
+
| `<NNN-slug>` (e.g. `003-onboarding`) | `mcp__serena__find_file` with mask `003-onboarding.md` under `wiki/work/requirements/` |
|
|
38
|
+
| `<NNN>` (e.g. `3` or `003`) | Pad to 3 digits; `mcp__serena__find_file` with mask `NNN-*.md` under `wiki/work/requirements/` |
|
|
39
|
+
| Empty / missing | List every requirement in `wiki/work/requirements/` whose `status` is `approved`, one row per file, and ask the user via `AskUserQuestion` to pick one |
|
|
40
|
+
|
|
41
|
+
If the file cannot be located, **stop** and report — do not invent or create.
|
|
42
|
+
|
|
43
|
+
### Step 2: Verify status is `approved`
|
|
44
|
+
|
|
45
|
+
Read the requirement's frontmatter `status` field. Refuse to continue with explicit guidance for any non-approved status:
|
|
46
|
+
|
|
47
|
+
| Current Status | Action |
|
|
48
|
+
|----------------|--------|
|
|
49
|
+
| `approved` | Continue to Step 3 |
|
|
50
|
+
| `draft` | Stop. Tell the user: "This requirement is still in draft. Run `/req-finalize <path>` first, then re-run `/req-extract-decisions`." |
|
|
51
|
+
| `retired` | Stop. Tell the user: "This requirement is retired. If a new architectural decision is needed, write a new requirement via `/req-create`." |
|
|
52
|
+
| `superseded` | Stop. Tell the user: "This requirement has been superseded. Run `/req-extract-decisions` against the successor requirement instead." |
|
|
53
|
+
|
|
54
|
+
### Step 3: Read the requirement and extract ASR candidates
|
|
55
|
+
|
|
56
|
+
Walk the requirement 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.
|
|
57
|
+
|
|
58
|
+
Scan with this map:
|
|
59
|
+
|
|
60
|
+
| Source Section | What to scan for | Likely decision category |
|
|
61
|
+
|----------------|------------------|--------------------------|
|
|
62
|
+
| Problem Statement | Mentions of scale, latency, integration boundaries, multi-tenancy | Structure, NFRs |
|
|
63
|
+
| Goals + Success Metrics | Quantitative thresholds (p95 latency, throughput, availability, error budget) | NFRs |
|
|
64
|
+
| User Stories acceptance criteria | Cross-system integrations, real-time requirements, transactional boundaries | Interfaces, NFRs |
|
|
65
|
+
| Constraints | Regulatory, compliance, vendor-mandated, contractual | Dependencies, security |
|
|
66
|
+
| Assumptions | Existing-system dependencies the requirement relies on | Dependencies |
|
|
67
|
+
| Non-Goals | What is NOT being built — informs scope of decisions, prevents over-broad decisions | Scope-bounding |
|
|
68
|
+
|
|
69
|
+
Build a candidate-ASR table. Every row must trace to a specific requirement location — quote or paraphrase verbatim, never invent:
|
|
70
|
+
|
|
71
|
+
| ASR# | ASR Statement (from requirement) | Source Section | Likely Decision Area | Likely Category |
|
|
72
|
+
|------|----------------------------------|----------------|----------------------|-----------------|
|
|
73
|
+
| A1 | "p95 search latency < 200ms with 10k active users" | SM-2 | search-infrastructure | NFR / Structure |
|
|
74
|
+
| A2 | "Must comply with SOC 2 access controls" | Constraint 1 | auth-and-access | Dependencies / Security |
|
|
75
|
+
| A3 | "Onboarding flow integrates with HRIS providers" | US-3 AC#2 | hris-integration | Interfaces |
|
|
76
|
+
|
|
77
|
+
**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.
|
|
78
|
+
|
|
79
|
+
If a candidate is borderline, exclude it and note the exclusion.
|
|
80
|
+
|
|
81
|
+
### Step 4: Cross-check existing decisions
|
|
82
|
+
|
|
83
|
+
For each candidate ASR, check whether an existing `accepted` decision already covers it.
|
|
84
|
+
|
|
85
|
+
**Procedure:**
|
|
86
|
+
|
|
87
|
+
1. `mcp__serena__list_dir` on `wiki/work/decisions/` to enumerate decision files
|
|
88
|
+
2. `Read` each decision file and walk every `## D*` block; collect blocks where `status: accepted` (or recently `proposed`)
|
|
89
|
+
3. For each candidate ASR, score each decision block using Tier-1 tag-overlap signal:
|
|
90
|
+
|
|
91
|
+
| Tier | Signal | Detection |
|
|
92
|
+
|------|--------|-----------|
|
|
93
|
+
| 1 | Tag overlap on the decision block | ≥ 1 shared tag with the ASR's likely decision area |
|
|
94
|
+
| 2 | Decision sub-title noun-phrase overlap | Substantial overlap |
|
|
95
|
+
| 3 | File-slug stem overlap | Only when the decision is a single-decision file |
|
|
96
|
+
|
|
97
|
+
4. Build the existing-coverage table:
|
|
98
|
+
|
|
99
|
+
| ASR# | Existing Decision Coverage | Coverage Status | Action |
|
|
100
|
+
|------|---------------------------|-----------------|--------|
|
|
101
|
+
| A1 | none | — | propose new decision |
|
|
102
|
+
| A2 | [[0003-auth-and-access\|DEC-0003#D2]] (tags: auth, soc2) | accepted | reuse — no new decision; add Source REQ back-link |
|
|
103
|
+
| A3 | [[0005-integrations\|DEC-0005#D1]] (tags: hris) | proposed | propose new decision if A3's scope is broader |
|
|
104
|
+
|
|
105
|
+
A `proposed` candidate is **not** a substitute for new coverage — flag it for the user.
|
|
106
|
+
|
|
107
|
+
### Step 5: Group ASRs into Decision Group candidates
|
|
108
|
+
|
|
109
|
+
Group ASRs **not already covered** by accepted decisions.
|
|
110
|
+
|
|
111
|
+
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.
|
|
112
|
+
|
|
113
|
+
Output the proposed grouping table:
|
|
114
|
+
|
|
115
|
+
| Group | ASRs | Suggested Decision Slug | Rationale (group/split signal) |
|
|
116
|
+
|-------|------|-----------------------|--------------------------------|
|
|
117
|
+
| G1 | A1 | search-infrastructure | Single decision area, single decider set |
|
|
118
|
+
| G2 | A3 | hris-integration | Distinct decision area; different reviewers from G1 |
|
|
119
|
+
|
|
120
|
+
### Step 6: Present and confirm via `AskUserQuestion`
|
|
121
|
+
|
|
122
|
+
Show the user three tables in this order:
|
|
123
|
+
|
|
124
|
+
1. The full ASR table from Step 3 (with the existing-coverage column folded in from Step 4)
|
|
125
|
+
2. The proposed grouping from Step 5
|
|
126
|
+
3. A per-group action prompt
|
|
127
|
+
|
|
128
|
+
For **each proposed group**, ask: "Create this as a decision now?" with options:
|
|
129
|
+
|
|
130
|
+
| Option | Meaning |
|
|
131
|
+
|--------|---------|
|
|
132
|
+
| `yes` | Confirm the group; the skill will write a placeholder row in the requirement and the user will run `/decision-create` next |
|
|
133
|
+
| `defer` | Keep the ASRs in the requirement's `## Linked Decisions` table as `not yet created` |
|
|
134
|
+
| `merge into <Gx>` | Combine this group with another listed group |
|
|
135
|
+
| `split` | Break this group into multiple smaller groups |
|
|
136
|
+
| `skip — already covered` | Drop the group; the ASR is handled by an existing decision |
|
|
137
|
+
| `skip — non-architectural` | Drop the group; handle directly via `/task-add --req REQ-NNN` |
|
|
138
|
+
|
|
139
|
+
### Step 7: Update the requirement's `## Linked Decisions` section
|
|
140
|
+
|
|
141
|
+
Use `Read` then `Edit` to populate the requirement's `## Linked Decisions` table. The edit is **surgical** — replace only the placeholder row inside that section.
|
|
142
|
+
|
|
143
|
+
For each row in the confirmed plan, use **wikilink format** for existing decisions:
|
|
144
|
+
|
|
145
|
+
| ASR | Decision | Status |
|
|
146
|
+
|-----|----------|--------|
|
|
147
|
+
| A1: <verbatim statement> | _to be created via `/decision-create group: search-infrastructure`_ | not yet created |
|
|
148
|
+
| A2: <verbatim statement> | `[[0003-auth-and-access\|DEC-0003#D2]]` | accepted |
|
|
149
|
+
| A3: <verbatim statement> | _to be created via `/decision-create hris-integration`_ | not yet created |
|
|
150
|
+
|
|
151
|
+
Rules for the row content:
|
|
152
|
+
|
|
153
|
+
| Column | Rule |
|
|
154
|
+
|--------|------|
|
|
155
|
+
| `ASR` | The ASR ID and verbatim (or near-verbatim) statement from Step 3 |
|
|
156
|
+
| `Decision` | If covered by existing decision: wikilink `[[NNNN-slug\|DEC-NNNN#DM]]`. If creating new: italicized placeholder with the exact `/decision-create` command |
|
|
157
|
+
| `Status` | `accepted` / `proposed` / `not yet created` |
|
|
158
|
+
|
|
159
|
+
Also update the requirement's frontmatter `updated` to today's date. Both edits use `Read` + `Edit` — never `sed`, `echo >>`, or `cat <<EOF`.
|
|
160
|
+
|
|
161
|
+
Append to `wiki/log.md`:
|
|
162
|
+
|
|
163
|
+
```
|
|
164
|
+
## [YYYY-MM-DD] req-extract-decisions | REQ-NNN <title> — N ASRs identified
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Step 8: Update existing decisions that reuse requirement ASRs
|
|
168
|
+
|
|
169
|
+
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 REQ:` line.
|
|
170
|
+
|
|
171
|
+
For each affected decision file:
|
|
172
|
+
|
|
173
|
+
1. `Read` the file
|
|
174
|
+
2. Locate the target decision's `### Links` section
|
|
175
|
+
3. Check whether `Source REQ: REQ-NNN` already exists — **skip if present** (idempotent)
|
|
176
|
+
4. `Edit` to append: `- Source REQ: [REQ-NNN](../requirements/NNN-slug.md)`
|
|
177
|
+
|
|
178
|
+
Touch only the target decision's `### Links`. Do not modify any decision's status, metadata, or content beyond the `### Links` append.
|
|
179
|
+
|
|
180
|
+
### Step 9: Report and instruct
|
|
181
|
+
|
|
182
|
+
Print a tabular completion report:
|
|
183
|
+
|
|
184
|
+
| Field | Value |
|
|
185
|
+
|-------|-------|
|
|
186
|
+
| Requirement | `REQ-NNN <title>` |
|
|
187
|
+
| ASRs identified | count |
|
|
188
|
+
| ASRs covered by existing decisions | count (linked back) |
|
|
189
|
+
| New decision groups proposed | count |
|
|
190
|
+
| New decision groups confirmed by user | count |
|
|
191
|
+
| ASRs deferred | count |
|
|
192
|
+
| ASRs skipped as non-architectural | count |
|
|
193
|
+
| Requirement `## Linked Decisions` updated | yes |
|
|
194
|
+
| Existing decision back-links added | count |
|
|
195
|
+
| Log entry | appended to wiki/log.md |
|
|
196
|
+
|
|
197
|
+
Then list the **next-action commands**, one per confirmed new group:
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
To create the proposed decisions, run each:
|
|
201
|
+
/decision-create group: search-infrastructure (from REQ-NNN)
|
|
202
|
+
/decision-create hris-integration (from REQ-NNN)
|
|
203
|
+
|
|
204
|
+
After each /decision-create completes, return to REQ-NNN's `## Linked Decisions` table
|
|
205
|
+
and update the placeholder row with the actual wikilink [[NNNN-slug|DEC-NNNN#DM]].
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
If any ASRs were skipped as non-architectural, also surface:
|
|
209
|
+
|
|
210
|
+
```
|
|
211
|
+
The following ASRs are best handled directly as tasks (no decision needed):
|
|
212
|
+
/task-add --req REQ-NNN "<short description for ASR Ax>"
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
The skill does **not** auto-invoke `/decision-create` or `/task-add`. It surfaces the commands; the user runs them.
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Output Formatting Rules (mandatory)
|
|
220
|
+
|
|
221
|
+
1. **Tables, not bullets.** ASR identification, existing-coverage analysis, and grouping proposals are all tables.
|
|
222
|
+
2. **Never auto-invoke `/decision-create` or `/task-add`.** Surface the exact commands; the user runs them.
|
|
223
|
+
3. **Never invent ASRs.** Every entry in the ASR table must trace to a specific requirement section, quoted or paraphrased verbatim.
|
|
224
|
+
4. **Boundary rule is enforced strictly.** Requirements ask for outcomes, decisions admit trade-offs. If a candidate ASR sounds like a solution, reformulate it as the underlying outcome.
|
|
225
|
+
5. **Requirement edits are surgical.** Use `Read` then `Edit` to update only the `## Linked Decisions` table and the `updated` field. Never rewrite the file.
|
|
226
|
+
6. **Idempotent back-links.** If `Source REQ: REQ-NNN` already exists in a decision's `### Links`, skip the edit. Re-running this skill against the same requirement must not duplicate links.
|
|
227
|
+
7. **Wikilinks for existing decisions.** Use `[[NNNN-slug\|DEC-NNNN#DM]]` format in the `## Linked Decisions` table.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## CRITICAL Rules
|
|
232
|
+
|
|
233
|
+
1. **Refuse to run on requirements not in `approved` status.** Step 2 is a hard gate.
|
|
234
|
+
2. **Never invent ASRs.** Every candidate is grounded in a specific requirement section.
|
|
235
|
+
3. **Never auto-create decisions.** Surface them as commands the user runs.
|
|
236
|
+
4. **Cross-check existing decisions before proposing duplicates.** Step 4 is mandatory.
|
|
237
|
+
5. **Bidirectional linkage is the contract.** The requirement's `## Linked Decisions` and any existing decision's `### Links` must both reflect the relationship. Re-running is idempotent.
|
|
238
|
+
6. **Per-decision tag overlap is the existing-coverage signal.**
|
|
239
|
+
7. **Maximum 3 sub-processes at a time** if delegating research or coverage analysis.
|
|
240
|
+
8. **Always terminate processes when done.**
|
|
241
|
+
9. **Never use `sed`/`echo >>`/`cat <<EOF`** — always `Read` + `Edit`.
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: req-finalize
|
|
3
|
+
description: Run completeness audit on a draft requirement, resolve gaps via Q&A, and flip status to approved
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
effort: high
|
|
7
|
+
argument-hint: <path/to/req.md, NNN-slug, or NNN>
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
# Finalize Requirement
|
|
15
|
+
|
|
16
|
+
Take a single **draft** requirement, surface every required-field gap or unresolved placeholder, resolve those gaps with the user, confirm stakeholder review, then flip the requirement's `status` from `draft` to `approved` in frontmatter.
|
|
17
|
+
|
|
18
|
+
Once a requirement is approved, it is **immutable in substance**. Future scope changes go through `/req-update`, which appends an `## Amendment N` block rather than rewriting prior content. This command is the one-way gate into that immutable state — get the audit right.
|
|
19
|
+
|
|
20
|
+
**Check `wiki/work/requirements/lifecycle.md` first.** It defines the required-non-empty fields, the status lifecycle, the file template, and the anti-patterns this audit must catch.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
**Target**: $ARGUMENTS
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Instructions
|
|
29
|
+
|
|
30
|
+
### Step 1: Resolve the requirement file
|
|
31
|
+
|
|
32
|
+
Parse `$ARGUMENTS` to identify the target file:
|
|
33
|
+
|
|
34
|
+
| Input form | Resolution |
|
|
35
|
+
|------------|------------|
|
|
36
|
+
| `<path>` (e.g. `wiki/work/requirements/REQ-003-search.md`) | Use as-is |
|
|
37
|
+
| `<NNN-slug>` (e.g. `003-search`) | Search `wiki/work/requirements/` for `NNN-slug.md` |
|
|
38
|
+
| `<NNN>` (e.g. `3` or `003`) | Pad to 3 digits; `mcp__serena__find_file` with mask `NNN-*.md` in `wiki/work/requirements/` |
|
|
39
|
+
| Empty / missing | List every requirement with `status: draft` across `wiki/work/requirements/` and ask the user via `AskUserQuestion` to pick one |
|
|
40
|
+
|
|
41
|
+
If the file cannot be located, **stop** and report — do not invent or create.
|
|
42
|
+
|
|
43
|
+
### Step 2: Read the file and verify status
|
|
44
|
+
|
|
45
|
+
1. **Read** the requirement with `Read`.
|
|
46
|
+
2. **Locate the `status:` field** in the YAML frontmatter.
|
|
47
|
+
3. **Verify the status is `draft`**:
|
|
48
|
+
|
|
49
|
+
| Current Status | Action |
|
|
50
|
+
|----------------|--------|
|
|
51
|
+
| `draft` | Continue to Step 3 |
|
|
52
|
+
| `approved` | Stop. Tell the user the requirement is already approved and immutable in substance; suggest `/req-update <file> <change>` for any amendment |
|
|
53
|
+
| `retired` | Stop. The requirement is no longer authoritative; finalizing makes no sense |
|
|
54
|
+
| `superseded` | Stop. A successor requirement has replaced this one — finalize the successor instead |
|
|
55
|
+
|
|
56
|
+
### Step 3: Audit the requirement against the quality bar
|
|
57
|
+
|
|
58
|
+
Inspect the file section by section and build a gap report. Required-field gaps need user resolution (Step 4); format-correction gaps are fixed in place during Step 5 without asking.
|
|
59
|
+
|
|
60
|
+
#### Required-field audit
|
|
61
|
+
|
|
62
|
+
| Required Field | Quality Bar | Failure mode to detect |
|
|
63
|
+
|----------------|-------------|------------------------|
|
|
64
|
+
| Problem Statement | 2-4 sentences; identifies what is broken, missing, or possible | Empty, single-sentence, or solution smuggled in |
|
|
65
|
+
| Goals (≥ 1) | Each row has an outcome-oriented goal AND a `Linked Success Metric` ID | Empty, vibes ("improve performance"), or goals without a metric link |
|
|
66
|
+
| Non-Goals (≥ 1) | At least one explicit out-of-scope row with a stated reason | Empty, "N/A", or row with no reason |
|
|
67
|
+
| Personas (≥ 1) | Named or named-role persona with context column and primary-goal column filled | "Users", "everyone", "the team" — not personas |
|
|
68
|
+
| User Stories (≥ 1) | Format `As <persona>, I want <capability> so that <outcome>`; each story has a non-empty Acceptance Criteria table | Stories without AC; AC written as test cases |
|
|
69
|
+
| Success Metrics (≥ 1) | Each row has signal + threshold + timeframe (When measured) | Missing threshold, missing timeframe, or vibes |
|
|
70
|
+
| owner | Single accountable name or role | Empty or template text |
|
|
71
|
+
| tags | 1-3 short area tags, non-empty | Empty or template `<area-1>, <area-2>` |
|
|
72
|
+
| Open Questions | Empty, OR every row has owner + resolution date | Lingering open questions block approval |
|
|
73
|
+
|
|
74
|
+
#### Format-correction audit (fix in place; no user question needed)
|
|
75
|
+
|
|
76
|
+
| Gap Type | Detection Pattern |
|
|
77
|
+
|----------|-------------------|
|
|
78
|
+
| Bullet-list user stories or goals | `- As a user, I want...` style — convert to prose-with-tables |
|
|
79
|
+
| Empty placeholder cells | Cells containing `…`, `...`, dashes used as placeholders, or whitespace |
|
|
80
|
+
| Placeholder text | `<...>`, `TBD`, `TODO`, `???`, `FIXME`, `[fill in]`, `<!-- ... -->` HTML comments |
|
|
81
|
+
| Stale `updated` | Date older than today |
|
|
82
|
+
| Anti-pattern: solution in problem statement | Implementation detail appearing in the Problem Statement |
|
|
83
|
+
|
|
84
|
+
#### Build the audit report
|
|
85
|
+
|
|
86
|
+
Output to the user **before any edits** as a tabular summary — never bullets:
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
File: wiki/work/requirements/REQ-003-search.md
|
|
90
|
+
Title: Federated search across knowledge bases
|
|
91
|
+
Current status: draft
|
|
92
|
+
Required-field gaps: N
|
|
93
|
+
Format-correction gaps: M
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Followed by a gaps table:
|
|
97
|
+
|
|
98
|
+
| Priority | Section | Gap | Resolution Strategy |
|
|
99
|
+
|----------|---------|-----|---------------------|
|
|
100
|
+
| 1 | Problem Statement | Empty | Ask user (Step 4) |
|
|
101
|
+
| 2 | Personas | Single row reads "Users" | Ask user (Step 4) |
|
|
102
|
+
| 3 | Success Metrics | SM-1 missing threshold | Ask user (Step 4) |
|
|
103
|
+
| 4 | User Stories | Bullet list, not prose-with-table | Auto-fix (Step 5) |
|
|
104
|
+
|
|
105
|
+
### Step 4: Resolve required-field gaps via `AskUserQuestion`
|
|
106
|
+
|
|
107
|
+
Resolve in this priority order — each layer feeds the next:
|
|
108
|
+
|
|
109
|
+
| Priority | Gap | Why first |
|
|
110
|
+
|----------|-----|-----------|
|
|
111
|
+
| 1 | Problem Statement | Everything else flows from this |
|
|
112
|
+
| 2 | Personas | Drive user stories |
|
|
113
|
+
| 3 | User Stories + Acceptance Criteria | The behavior contract |
|
|
114
|
+
| 4 | Success Metrics (signal + threshold + timeframe) | Required for every Goal link |
|
|
115
|
+
| 5 | Goal-to-metric linkage | Goals are vibes without metrics |
|
|
116
|
+
| 6 | Non-Goals (≥ 1 with reason) | Forces scope discipline |
|
|
117
|
+
| 7 | Owner + Stakeholders | Accountability and review surface |
|
|
118
|
+
| 8 | Tags | Indexing and downstream queries |
|
|
119
|
+
| 9 | Constraints / Assumptions / Open Questions | Lower-stakes; address last |
|
|
120
|
+
|
|
121
|
+
**Question style:**
|
|
122
|
+
|
|
123
|
+
- Frame each question with the relevant context already in the file (quote the section being repaired).
|
|
124
|
+
- For Success Metrics, **demand explicit numbers** — refuse to accept "we'll measure later" or "TBD".
|
|
125
|
+
- For Personas, **demand a name or named role plus context plus goal** — refuse generic "users", "everyone", "the team".
|
|
126
|
+
- For Acceptance Criteria, **demand observable user-facing behavior** — refuse test-case phrasing.
|
|
127
|
+
- For Problem Statement, **demand user-visible language** — refuse implementation smuggled in.
|
|
128
|
+
|
|
129
|
+
If the user genuinely lacks an answer to a required-field gap, **do not fabricate**. Leave status as `draft`, report which gaps remain, and stop.
|
|
130
|
+
|
|
131
|
+
### Step 5: Apply edits
|
|
132
|
+
|
|
133
|
+
Use **`Edit`** for every change — never `sed`/`awk`/`echo >>`/`cat <<EOF` rewrites.
|
|
134
|
+
|
|
135
|
+
Apply edits in this order:
|
|
136
|
+
|
|
137
|
+
1. **Fill resolved required-field content** — one `Edit` per distinct change.
|
|
138
|
+
2. **Convert any bullet-list user stories or goals to the template's prose-and-table form** — one Edit per converted block.
|
|
139
|
+
3. **Fill empty placeholder cells** (`…`, `...`, dashes, whitespace).
|
|
140
|
+
4. **Strip any remaining placeholder text** (`<...>`, `TBD`, `TODO`, `???`, `FIXME`, `[fill in]`, leftover HTML comments).
|
|
141
|
+
5. **Update `updated`** in frontmatter to today's date (single Edit).
|
|
142
|
+
6. **Final edit: flip `status: draft` → `status: approved`.** This is the last edit applied — only after every other gap is resolved.
|
|
143
|
+
|
|
144
|
+
### Step 6: Re-audit checklist before flipping status
|
|
145
|
+
|
|
146
|
+
Re-read the requirement. Finalization is allowed **only when every box below is checked**:
|
|
147
|
+
|
|
148
|
+
- [ ] Problem Statement is 2-4 sentences; no implementation detail smuggled in
|
|
149
|
+
- [ ] At least 1 Goal row, each linked to a Success Metric ID present in the Success Metrics table
|
|
150
|
+
- [ ] At least 1 Non-Goal row with a stated reason
|
|
151
|
+
- [ ] At least 1 named (or named-role) Persona with context and primary goal filled
|
|
152
|
+
- [ ] At least 1 User Story with a non-empty Acceptance Criteria table; AC describes observable behavior, not test cases
|
|
153
|
+
- [ ] At least 1 Success Metric row with signal, threshold, and timeframe all filled
|
|
154
|
+
- [ ] `owner` is a single accountable name or role (not template text, not empty)
|
|
155
|
+
- [ ] `tags` is non-empty (1-3 area tags)
|
|
156
|
+
- [ ] Open Questions is either empty OR every row has owner + resolution date
|
|
157
|
+
- [ ] No `<...>`, `TBD`, `TODO`, `???`, `FIXME`, `[fill in]`, or empty placeholder cells remain in any required section
|
|
158
|
+
- [ ] No bullet-list user stories or goals remain
|
|
159
|
+
- [ ] `updated` is today's date
|
|
160
|
+
- [ ] `status: approved` is the **last** edit applied, only after every other check passes
|
|
161
|
+
|
|
162
|
+
If any item fails, **return to Step 4** or Step 5. **Do not flip status while gaps remain.**
|
|
163
|
+
|
|
164
|
+
### Step 7: Stakeholder confirmation gate
|
|
165
|
+
|
|
166
|
+
Before flipping the status edit, use `AskUserQuestion` to ask the user explicitly: have the named **stakeholders** reviewed this requirement, or been notified that approval is imminent?
|
|
167
|
+
|
|
168
|
+
| User answer | Action |
|
|
169
|
+
|-------------|--------|
|
|
170
|
+
| Yes — stakeholders have reviewed | Continue; apply the `status: draft` → `status: approved` edit. |
|
|
171
|
+
| No — they have not | **Stop.** Leave `status: draft` in place. Report what's blocking and suggest the user circulate the draft before re-running `/req-finalize`. |
|
|
172
|
+
|
|
173
|
+
### Step 8: Update the wiki index
|
|
174
|
+
|
|
175
|
+
Edit `wiki/work/requirements/index.md` to update this requirement's row (status text `draft` → `approved`; approved is still active so the row stays):
|
|
176
|
+
|
|
177
|
+
| Column | New value |
|
|
178
|
+
|--------|-----------|
|
|
179
|
+
| `Status` | `approved` |
|
|
180
|
+
|
|
181
|
+
If this requirement's row does not yet exist in the index table, insert a new row using the column format:
|
|
182
|
+
|
|
183
|
+
| Column | Format |
|
|
184
|
+
|--------|--------|
|
|
185
|
+
| `ID` | `[REQ-NNN](requirements/NNN-slug.md)` |
|
|
186
|
+
| `Title` | The requirement's initiative title |
|
|
187
|
+
| `Status` | `approved` |
|
|
188
|
+
| `Created` | The requirement's `created:` date |
|
|
189
|
+
| `Owner` | The requirement's confirmed owner |
|
|
190
|
+
| `Linked Decisions` | `—` (filled later by `/req-extract-decisions`) |
|
|
191
|
+
| `Linked Tasks` | `—` (filled later by `/task-add --req`) |
|
|
192
|
+
|
|
193
|
+
Append to `wiki/log.md`:
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
## [YYYY-MM-DD] req-approved | REQ-NNN <title>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Use `Read` then `Edit` for the index update — never `echo >>` or `sed`.
|
|
200
|
+
|
|
201
|
+
### Step 9: Refresh the hot cache
|
|
202
|
+
|
|
203
|
+
Approving a requirement is durable, cross-session-relevant wiki state. Run the **Hot Cache Refresh** procedure — defined in `/wiki-ingest` Step 8 (`lib/skills/wiki-ingest/SKILL.md`) — to regenerate `wiki/hot.md` in full, surfacing this newly approved requirement under Recent Changes. Do not restate the procedure here; follow it as written.
|
|
204
|
+
|
|
205
|
+
### Step 10: Report completion and suggest next steps
|
|
206
|
+
|
|
207
|
+
Print a tabular summary:
|
|
208
|
+
|
|
209
|
+
| Field | Value |
|
|
210
|
+
|-------|-------|
|
|
211
|
+
| File | `<path>` |
|
|
212
|
+
| Title | `<requirement title>` |
|
|
213
|
+
| Old → New status | `draft → approved` |
|
|
214
|
+
| Required-field gaps resolved | count |
|
|
215
|
+
| Format fixes applied | count |
|
|
216
|
+
| Stakeholder confirmation | yes |
|
|
217
|
+
| Index updated | yes |
|
|
218
|
+
| Log entry | appended to wiki/log.md |
|
|
219
|
+
| Suggested next steps | see below |
|
|
220
|
+
|
|
221
|
+
Suggested next steps:
|
|
222
|
+
|
|
223
|
+
| Suggestion | When to use it |
|
|
224
|
+
|------------|----------------|
|
|
225
|
+
| `/req-extract-decisions <file>` | The default next step — extract Architecturally Significant Requirements and propose decision candidates |
|
|
226
|
+
| `/task-add --req REQ-NNN <description>` | Only when the requirement's scope is small enough to skip decisions entirely |
|
|
227
|
+
| `/req-update <file> <change>` | If a scope change surfaces post-approval — appends an `## Amendment N` block; never rewrites |
|
|
228
|
+
|
|
229
|
+
Do **not** auto-create downstream artifacts — present them as suggestions only.
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Output Formatting Rules (mandatory)
|
|
234
|
+
|
|
235
|
+
1. **Tables not bullets** — every audit summary, gap report, and re-audit checklist uses tables
|
|
236
|
+
2. **One Edit per gap** — keep edits surgical; do not rewrite whole sections to fix a single placeholder cell
|
|
237
|
+
3. **Never alter approved requirements** — refuse to run on a target whose status is `approved`, `retired`, or `superseded`; suggest `/req-update` for amendments
|
|
238
|
+
4. **Status flip is the LAST edit** — apply it only after the Step 6 re-audit checklist passes AND the Step 7 stakeholder gate returns yes
|
|
239
|
+
5. **Never fabricate content** — if the user lacks an answer for a required-field gap, leave `status: draft`, report which gaps remain, and stop
|
|
240
|
+
6. **Present tense, full sentences** when filling content
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## CRITICAL Rules
|
|
245
|
+
|
|
246
|
+
1. **Status flip is one-way and final** — only flip to `approved` after every Step 6 checklist item passes AND Step 7 stakeholder confirmation returns yes
|
|
247
|
+
2. **Re-audit MUST run before flipping** — the Step 6 checklist is mandatory; never skip it
|
|
248
|
+
3. **Never use `sed`/`awk`/`echo >>`/`cat <<EOF`** — always `Edit`
|
|
249
|
+
4. **Never auto-create downstream artifacts** — `/req-extract-decisions`, `/task-add`, decisions, and tasks are user-invoked
|
|
250
|
+
5. **Maximum 3 sub-processes at a time** if delegating any sub-step
|
|
251
|
+
6. **No fabrication** — refuse to fill content the user could not supply
|