@codewizard-dt/bootstrap 6.0.0 → 6.1.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.
Files changed (44) hide show
  1. package/LICENSE.md +105 -0
  2. package/README.md +12 -0
  3. package/lib/scripts/README.md +4 -3
  4. package/lib/scripts/bootstrap-prefs.js +25 -2
  5. package/lib/scripts/git-prefs.js +123 -0
  6. package/lib/scripts/install-global.sh +3 -0
  7. package/lib/scripts/merge-gitignore.sh +11 -5
  8. package/lib/scripts/migrate-project.sh +1 -1
  9. package/lib/scripts/rename-wiki-ids.js +2 -2
  10. package/lib/scripts/sync-wiki-scaffold.sh +5 -11
  11. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  12. package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
  13. package/lib/scripts/templates/guides/stubs/serena.md +4 -1
  14. package/lib/scripts/templates/settings-deny.json +1 -1
  15. package/lib/scripts/templates/wiki/conventions.md +1 -1
  16. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +1 -1
  17. package/lib/skills/README.md +2 -1
  18. package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +2 -2
  19. package/lib/skills/_shared/ID-RESOLUTION.md +2 -2
  20. package/lib/skills/_shared/LOG-APPEND.md +34 -0
  21. package/lib/skills/_shared/SKILL-BOILERPLATE.md +1 -1
  22. package/lib/skills/adr-create/SKILL.md +2 -2
  23. package/lib/skills/adr-deprecate/SKILL.md +1 -1
  24. package/lib/skills/adr-extract/SKILL.md +1 -1
  25. package/lib/skills/adr-finalize/SKILL.md +2 -1
  26. package/lib/skills/autopilot/SKILL.md +1 -1
  27. package/lib/skills/bug-assess/SKILL.md +1 -1
  28. package/lib/skills/bug-triage/SKILL.md +1 -1
  29. package/lib/skills/git-commit/SKILL.md +18 -27
  30. package/lib/skills/prd-create/SKILL.md +2 -2
  31. package/lib/skills/prd-deprecate/SKILL.md +1 -1
  32. package/lib/skills/prd-finalize/SKILL.md +1 -1
  33. package/lib/skills/socratic-qa/SKILL.md +163 -0
  34. package/lib/skills/task-create/SKILL.md +1 -1
  35. package/lib/skills/uat-create/SKILL.md +1 -1
  36. package/lib/skills/uat-skip/SKILL.md +19 -29
  37. package/lib/skills/uat-walk/UAT-CORE.md +1 -1
  38. package/lib/skills/wiki-archive/SKILL.md +1 -1
  39. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  40. package/lib/skills/wiki-lint/SKILL.md +1 -1
  41. package/lib/skills/wiki-query/SKILL.md +1 -1
  42. package/lib/skills/wiki-rotate-log/SKILL.md +14 -24
  43. package/lib/skills/wiki-tidy/SKILL.md +5 -12
  44. package/package.json +3 -3
@@ -0,0 +1,34 @@
1
+ # LOG-APPEND — shared procedure for appending to wiki/log.md
2
+
3
+ The mechanic for appending one entry to `wiki/log.md` — check its size, **force-rotate first with no confirmation** when it has reached the threshold, then append — lives here once. Every `SKILL.md` that writes a log entry supplies only its entry text (see **Inputs**) and runs this procedure instead of a bare "`Read` `wiki/log.md`, then `Edit` to append." This is not a nudge: rotation at threshold is automatic and unconditional, never a question put to the user.
4
+
5
+ ## Inputs
6
+
7
+ | Input | Meaning |
8
+ |-------|---------|
9
+ | `entry` | The exact log entry text to append (the `## [YYYY-MM-DD] <op> \| <subject>` line plus its 1-3 sentence body), as defined by the calling skill. |
10
+
11
+ ## Procedure
12
+
13
+ 1. **Read** `wiki/log.md`. Count its total lines (this is the same `Read` the caller needs anyway to `Edit` it — never a second, separate read).
14
+ 2. **If the line count is 200 or more: rotate now, forced, no confirmation, no question asked.** Run the rotation mechanic exactly as `lib/skills/wiki-rotate-log/SKILL.md` Steps 2 and 4 define it (generate the timestamp, `git mv` the old log to `log-<timestamp>.md`, carry forward any `> Archives:` pointer, create a fresh `log.md` with the standard header and a `rotate` entry recording the forced rotation) — do not restate those steps here, follow them as written. This happens unconditionally at threshold; it is never skipped, deferred, or asked about.
15
+ 3. **Append `entry`.** `Edit` the (possibly just-rotated, now-current) `wiki/log.md` to add `entry` at the bottom. One `Edit` call.
16
+
17
+ ## CRITICAL rules
18
+
19
+ - **Rotation at threshold is forced, never optional.** No skill may ask the user "rotate now?" as part of a routine append — that question belongs only to a human directly invoking `/wiki-rotate-log` itself below threshold (an explicit early rotation request), never to this procedure.
20
+ - **The threshold is 200 lines**, defined once in `lib/skills/wiki-rotate-log/SKILL.md` — this doc reads that value from there rather than restating it, so the two can never drift apart.
21
+ - **Never truncate.** Rotation (when it fires) moves content to a timestamped archive file; nothing is deleted.
22
+ - **One `Edit` per entry.** Never `sed`, `awk`, or `echo >>` to append.
23
+ - A caller that needs to `skip` writing its own entry (because a batch/shared procedure already wrote one, e.g. `ARCHIVE-WORK-ITEM.md`'s `log: skip`) does not invoke this procedure at all for that call — nothing to append, nothing to rotate for.
24
+
25
+ ## Caller deltas
26
+
27
+ What each consumer passes as `entry`. Anything not listed here is the caller's own logic and stays in its `SKILL.md`.
28
+
29
+ | Consumer | `entry` |
30
+ |----------|---------|
31
+ | `task-create`, `adr-create`, `adr-finalize`, `adr-extract`, `adr-deprecate`, `prd-create`, `prd-finalize`, `prd-deprecate`, `uat-create`, `uat-skip`, `bug-triage`, `wiki-lint`, `wiki-query`, `wiki-archive`, `autopilot` | each skill's own documented entry format (unchanged — see that `SKILL.md`'s own log-entry section) |
32
+ | `bug-assess` | one combined entry for the whole pass, not one per bug |
33
+ | `_shared/ARCHIVE-WORK-ITEM.md`, `_shared/ARCHIVE-WORK-ITEM.md`'s in-place-close section | the caller's `log` input, or the shared doc's own default entry, unless `log: skip` |
34
+ | `uat-walk/UAT-CORE.md` Step 7 (shared by `uat-walk`, `uat-auto`, `uat-auto-plus`) | the Closure-procedure entry documented there |
@@ -23,7 +23,7 @@ The line stays inline because it is the instruction to read `mcp-tools.md`: hidi
23
23
 
24
24
  - Never use `sed`, `awk`, `perl -i`, `echo >>`, `cat <<EOF`, or any shell redirection to modify a markdown or config file.
25
25
  - Use `Read` then `Edit`: one `Edit` per change, even when there are many. Never `Write` to rewrite an existing file in full.
26
- - Appending to `wiki/log.md` or an index file is a `Read` then `Edit`, not `echo >>`.
26
+ - Appending to an index file is a `Read` then `Edit`, not `echo >>`. Appending to `wiki/log.md` specifically follows `lib/skills/_shared/LOG-APPEND.md` (forces a rotation first at threshold, never asks).
27
27
  - Bash is reserved for commands with no dedicated tool (for example `git mv`).
28
28
 
29
29
  See `wiki/guides/mcp-tools.md` "Common anti-patterns". Each violation triggers a permission prompt.
@@ -199,8 +199,8 @@ flowchart LR
199
199
  **Default to `proposed`** — create-time supersession is rare; `/adr-finalize` enforces it atomically.
200
200
  4. Don't delete/mutate existing index rows beyond what supersession requires (append-mostly).
201
201
 
202
- ## Step 7: Append to `wiki/log.md` (`Edit` only)
203
- `## [YYYY-MM-DD] adr-create | ADR-NNNN <Decision-Group Title>`
202
+ ## Step 7: Append to `wiki/log.md`
203
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to `## [YYYY-MM-DD] adr-create | ADR-NNNN <Decision-Group Title>`.
204
204
 
205
205
  ## Step 8: Cross-link from related artifacts
206
206
  For any decision prompted by an active task/feature, link both ways (Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene): in the source task file append `**Decision**: [[ADR-NNNN-slug|ADR-NNNN#DM: title]]`; in the decision's `### Links` list the source task path.
@@ -125,7 +125,7 @@ Use `Read` then `Edit`. If the row is absent, note it and continue.
125
125
 
126
126
  ### Step 6: Append to wiki/log.md
127
127
 
128
- Append one entry to `wiki/log.md`:
128
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
129
129
 
130
130
  ```
131
131
  ## [YYYY-MM-DD] adr-deprecated | ADR-NNNN#DM <title> — reason: <one-line summary of reason>
@@ -165,7 +165,7 @@ Rules for the row content:
165
165
 
166
166
  Also update the PRD's frontmatter `updated` to today's date. Both edits use `Read` + `Edit`.
167
167
 
168
- Append to `wiki/log.md` (re-read it immediately before editing) — both modes:
168
+ Follow `lib/skills/_shared/LOG-APPEND.md` — both modes — with `entry` set to:
169
169
 
170
170
  ```
171
171
  ## [YYYY-MM-DD] adr-extract | <PRD-NNNN or document path> <title> — N ASRs identified
@@ -135,7 +135,8 @@ The file is never moved: a cross-group `superseded` flip (Step 4.6) edits the su
135
135
 
136
136
  `Read` then `Edit` for all index edits.
137
137
 
138
- ## Step 7: Append log entry (`wiki/log.md`, `Edit` only)
138
+ ## Step 7: Append log entry
139
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
139
140
  - No supersession: `## [YYYY-MM-DD] adr-accepted | ADR-NNNN#DM <Decision Title>`
140
141
  - Supersession: `## [YYYY-MM-DD] adr-superseded | ADR-MMMM#DK superseded by ADR-NNNN#DM`
141
142
 
@@ -74,7 +74,7 @@ Reached only when `/whats-next` reported no open work at all.
74
74
 
75
75
  - Record the source in `## Notes` as a path (`raw/research/<slug>/index.md`). Set `derived_from:` only when a `wiki/knowledge/sources/` page for that report already exists; otherwise omit it.
76
76
  - The roadmap's own refusal rules still hold (vague Goal, missing Owner, zero items): if the report yields no concrete recommendation, write nothing and report `Autopilot: research produced no actionable recommendation — no roadmap created.`
77
- 4. **Log it.** Append `## [YYYY-MM-DD] roadmap | ROADMAP-NNNN <title>` plus one sentence — `created by /autopilot from raw/research/<slug>/` — to `wiki/log.md` (append-only; never edit an existing entry).
77
+ 4. **Log it.** Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to `## [YYYY-MM-DD] roadmap | ROADMAP-NNNN <title>` plus one sentence — `created by /autopilot from raw/research/<slug>/`.
78
78
  5. **Stop.** Do not call `/power-mode` in this tick. Research plus roadmap creation is already a long tick, and the next tick's Stage A finds the new roadmap's inline items and drives them.
79
79
 
80
80
  ## Report
@@ -42,7 +42,7 @@ For each confirmed bug, apply the updates per the Step 6/7 procedure in `lib/ski
42
42
 
43
43
  Outcomes this pass does **not** handle: starting work (`in-progress`) and rejection (`wontfix` / `duplicate` / `cannot-reproduce`). Those require the impact/workaround/resolution rigor of `/bug-triage` — never shortcut them here.
44
44
 
45
- Append **one** combined entry to `wiki/log.md` for the whole pass, not one per bug:
45
+ Follow `lib/skills/_shared/LOG-APPEND.md` with **one** combined `entry` for the whole pass, not one per bug:
46
46
 
47
47
  ```
48
48
  ## [YYYY-MM-DD] bug-assess | batch triage
@@ -105,7 +105,7 @@ For active outcomes (Start work / Defer), skip this step entirely — the file s
105
105
 
106
106
  ### Step 9: Append Log Entry
107
107
 
108
- Append to `wiki/log.md`:
108
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
109
109
 
110
110
  ```
111
111
  ## [YYYY-MM-DD] bug-triage | BUG-NNNN <title>
@@ -16,25 +16,21 @@ user-invocable: true
16
16
 
17
17
  Before anything else, confirm the working directory is the repository root — every later step (`git status`/`git diff HEAD`, manifest Detection, the `--project .` preference reads below, and `git-commit`'s own `git add .`) assumes it. Running from a subdirectory would silently stage, diff, or bump only that subtree instead of the whole repo.
18
18
 
19
+ One command does the `cd`, the repo facts, and the three preference reads (next section):
20
+
19
21
  ```bash
20
- cd "$(git rev-parse --show-toplevel)"
22
+ cd "$(git rev-parse --show-toplevel)" && node ~/.claude/git-prefs.js
21
23
  ```
22
24
 
23
- If this fails (not inside a git repo at all), **STOP** and report: `/git-commit must run inside a git repository — no repo root found from the current directory.` Otherwise the working directory is now the repo root; proceed for the rest of this run without re-checking.
25
+ If the `cd` fails (not inside a git repo at all), **STOP** and report: `/git-commit must run inside a git repository — no repo root found from the current directory.` Otherwise the working directory is now the repo root; proceed for the rest of this run without re-checking.
24
26
 
25
27
  **Worktree-safe by construction**: `--show-toplevel` resolves to the current *worktree's own* root when run from inside a linked worktree, not the main checkout's — exactly the directory this run should operate in, so no worktree-specific branch is needed here. (Contrast with `--git-dir`/`--git-common-dir`, which resolve to the *shared* `.git` location across all worktrees — the right tool when code needs the common git directory instead, as in `file-suggestion.sh`'s worktree fix, but the wrong one here.)
26
28
 
27
29
  ### Read the three preferences that govern this skill
28
30
 
29
- Three stored preferences change what this command does. Read **all three, once, before Step 1** — never mid-run, and never once per file:
30
-
31
- ```bash
32
- node ~/.claude/bootstrap-prefs.js --get gitCommit.versionBump --project . 2>/dev/null || echo unset
33
- node ~/.claude/bootstrap-prefs.js --get gitCommit.autoPush --project . 2>/dev/null || echo unset
34
- node ~/.claude/bootstrap-prefs.js --get gitCommit.lint --project . 2>/dev/null || echo unset
35
- ```
31
+ Three stored preferences change what this command does. The `## prefs` block of the command above prints **all three** (`gitCommit.versionBump`, `gitCommit.autoPush`, `gitCommit.lint`) — read them once, before Step 1, never mid-run, and never once per file.
36
32
 
37
- `--project .` is required. All three keys are `scope: either`, so the answer resolves **project file → global file → schema default**; dropping the flag would read the machine-wide answer even in a repo that overrides it. If any command fails — bootstrap was never installed globally, or `node` is not on PATH — treat that answer as `unset`.
33
+ `git-prefs.js` resolves them with the project's repo root as `--project`. All three keys are `scope: either`, so each answer resolves **project file → global file → schema default**. If the command fails — bootstrap was never installed globally, or `node` is not on PATH — treat every answer as `unset`. The same output also carries `## repo` (branch, upstream), `## manifests`, `## status`, `## log` and `## diff`; this first call's status/diff are pre-lint, so Step 3 re-runs it.
38
34
 
39
35
  `unset` means *nobody has ever been asked*. For `gitCommit.versionBump` and `gitCommit.autoPush` this keeps today's behavior; it never invents one. `gitCommit.lint` is the deliberate exception: it is opt-in by explicit design, so `unset` (and `false`) both mean **do not lint** — a fresh install must never lint before the user has said yes. Mention an `unset` key **once**, in the final report, never as a mid-run interruption.
40
36
 
@@ -68,13 +64,19 @@ Use `Edit` per file for every change. Edit only — see `~/.claude/skills/_share
68
64
 
69
65
  ## Step 3: Assess Changes
70
66
 
71
- **Always run all three commands fresh.** Do not rely on session context, prior output, or anything produced earlier in the conversation — those reflect only a subset of what may have changed. The commit message must be based on the complete current working-tree state.
67
+ **Always run it fresh.** Do not rely on session context, prior output, or anything produced earlier in the conversation — including the Step 0 call, which predates any lint or comment edits. The commit message must be based on the complete current working-tree state.
72
68
 
73
- Run all three in parallel:
69
+ ```bash
70
+ node ~/.claude/git-prefs.js
71
+ ```
74
72
 
75
- - `git status` — see all modified/untracked files
76
- - `git diff HEAD` — see exact diffs for ALL staged and unstaged changes
77
- - `git log --oneline -10` — see recent commit history for context
73
+ One call returns everything this step needs:
74
+
75
+ - `## status` — all modified/untracked files (`git status --short`)
76
+ - `## diff` — exact diffs for ALL staged and unstaged changes (`git diff HEAD`)
77
+ - `## log` — recent commit history for context (`git log --oneline -10`)
78
+ - `## manifests` — every version-bearing manifest with its current version, used by Step 5
79
+ - `## repo` — current branch and upstream, used by Step 7
78
80
 
79
81
  ## Step 4: Summarize Changes, and Recommend a Semver Bump Only If It Will Be Used
80
82
 
@@ -155,18 +157,7 @@ Find and update version numbers in project files.
155
157
 
156
158
  ### Detection
157
159
 
158
- Run this command to find all manifest files anywhere in the repo (excluding `node_modules` and hidden dirs):
159
-
160
- ```bash
161
- find . \( -name node_modules -o -name .git \) -prune -o \
162
- \( -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" \
163
- -o -name "setup.cfg" -o -name "VERSION" -o -name "version.txt" \) \
164
- -print
165
- ```
166
-
167
- Filter results:
168
- - For `package.json`: only include files that contain a `"version"` field (skip `node_modules` entries even if the prune missed them)
169
- - For `pyproject.toml` / `Cargo.toml` / `setup.cfg`: only include files with an actual `version =` line under a recognized section
160
+ Use the `## manifests` block from Step 3's `git-prefs.js` output — no separate search. It lists every `package.json`, `pyproject.toml`, `Cargo.toml`, `setup.cfg`, `VERSION` and `version.txt` in the repo (tracked or untracked, `.gitignore` respected so `node_modules` never appears) that carries a real version, as `<path> <current version>`. Files without a version field are already filtered out.
170
161
 
171
162
  **There is no "root only" rule.** A manifest anywhere in the tree counts. Monorepo layouts with no root-level manifest are normal — update every package found.
172
163
 
@@ -94,8 +94,8 @@ Sections in order: `# PRD-NNNN: <Title>` · `## Problem Statement` · `## Goals`
94
94
 
95
95
  **Refuse to write** if any required-non-empty field is missing or fails its bar — loop back to Step 4.
96
96
 
97
- ## Step 7: Update indexes + log (`Edit` only)
98
- Append (or replace the placeholder row) under `## Active` in `wiki/work/requirements/index.md` (a new draft is always Active; `/prd-deprecate` later moves it to `## Closed`) using the format documented at the top of that file: `- [PRD-NNNN — Title](PRD-NNNN-slug.md) — one-line summary · status`, in ascending ID order. Append to `wiki/log.md`: `## [YYYY-MM-DD] prd-create | PRD-NNNN <title>`.
97
+ ## Step 7: Update indexes + log
98
+ Append (or replace the placeholder row) under `## Active` in `wiki/work/requirements/index.md` (a new draft is always Active; `/prd-deprecate` later moves it to `## Closed`) using the format documented at the top of that file: `- [PRD-NNNN — Title](PRD-NNNN-slug.md) — one-line summary · status`, in ascending ID order (`Edit` only). Then follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to `## [YYYY-MM-DD] prd-create | PRD-NNNN <title>`.
99
99
 
100
100
  ## Step 8: Cross-link related artifacts
101
101
  If prompted by an existing task/research note/reference, link both ways (`Read` then `Edit`): source artifact gets `**Requirement**: PRD-NNNN ([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.
@@ -110,7 +110,7 @@ Use `Read` then `Edit`. If the row is already absent from Active, note it and co
110
110
 
111
111
  ### Step 6: Append to wiki/log.md
112
112
 
113
- Append one entry to `wiki/log.md`:
113
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
114
114
 
115
115
  ```
116
116
  ## [YYYY-MM-DD] prd-deprecated | PRD-NNNN <title> — reason: <one-line summary of reason>
@@ -183,7 +183,7 @@ If this requirement's row does not yet exist in the index table, insert a new ro
183
183
  | `Linked Decisions` | `—` (filled later by `/adr-extract`) |
184
184
  | `Linked Tasks` | `—` (filled later by `/task-create --req`) |
185
185
 
186
- Append to `wiki/log.md`:
186
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
187
187
 
188
188
  ```
189
189
  ## [YYYY-MM-DD] prd-approved | PRD-NNNN <title>
@@ -0,0 +1,163 @@
1
+ ---
2
+ name: socratic-qa
3
+ description: Interrogate the user with an exhaustive, Socratic question loop until the agent has zero remaining doubts about the task at hand — then restate the task and get explicit confirmation before any work begins
4
+ category: planning
5
+ model: claude-sonnet-5
6
+ effort: high
7
+ argument-hint: <task, idea, or request to clarify before acting>
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
+ # Socratic Q&A
14
+
15
+ Drive a **Socratic question loop** about the task below. The goal is a single state: **you have no remaining doubts** about what is being asked, why, for whom, what "done" looks like, and what must not happen. Until that state is reached, you ask; you do not guess, assume, or start building.
16
+
17
+ **Task**: $ARGUMENTS
18
+
19
+ > *Asking is cheap; rework is expensive.* A wrong assumption discovered after implementation costs orders of magnitude more than the question that would have exposed it.
20
+
21
+ This skill can be invoked directly (`/socratic-qa <task>`) or referenced by any other skill or agent that needs to clarify a task before acting. It produces **shared understanding**, not artifacts — it writes no files unless the user asks.
22
+
23
+ ## When to use
24
+
25
+ | Use | Skip |
26
+ |-----|------|
27
+ | Request is ambiguous, underspecified, or has multiple plausible readings | Task is a trivial, fully specified one-liner |
28
+ | Cost of a wrong guess is high (migrations, public APIs, destructive ops, multi-file features) | The answer is already in the code, wiki, memory, or conversation — go read it |
29
+ | Stakeholders, constraints, or success criteria are unstated | User has explicitly said "just do it, use your judgment" |
30
+ | Work will be delegated to subagents that can't ask follow-ups themselves | |
31
+
32
+ ---
33
+
34
+ ## The method
35
+
36
+ ### 1. Ground yourself first — never ask what you can look up
37
+
38
+ Before asking anything, exhaust the cheap sources: the codebase (Serena `find_symbol` / `get_symbols_overview`), `CLAUDE.md`, `wiki/` (start at `wiki/index.md`), Serena memories (`list_memories` / `read_memory`), recent git history, and the conversation so far. **Questions the repo can answer are a failure of diligence, not diligence.** Ask only about what is genuinely unknowable without the user: intent, preference, priority, business context, taste, risk tolerance.
39
+
40
+ ### 2. Build the doubt inventory
41
+
42
+ Silently enumerate every open question across these dimensions. This is your checklist; the loop ends when every row is resolved or explicitly marked out of scope by the user.
43
+
44
+ | Dimension | Probe for |
45
+ |-----------|-----------|
46
+ | **Purpose** | The real problem behind the request. Why now? What happens if this isn't done? |
47
+ | **Audience** | Who uses/benefits/maintains the result? Their skill level and context |
48
+ | **Scope — in** | Exactly what must be included. Boundaries of "the thing" |
49
+ | **Scope — out** | What a reader might wrongly assume is included. Explicit non-goals |
50
+ | **Success criteria** | Observable, testable definition of done. How will the user verify it? |
51
+ | **Inputs & outputs** | Data, formats, interfaces, files touched, shape of the deliverable |
52
+ | **Constraints** | Tech stack, performance, compatibility, deadlines, budget, legal/compliance, house conventions |
53
+ | **Dependencies** | Other systems, tasks, people, or decisions this relies on or unblocks |
54
+ | **Edge cases & failure modes** | Empty/huge/malformed input, concurrency, partial failure, rollback, "what if X is missing" |
55
+ | **Risks & irreversibility** | Anything destructive, outward-facing, or hard to undo; what must never happen |
56
+ | **Priorities & trade-offs** | When goals conflict (speed vs. quality, scope vs. time), which wins |
57
+ | **Existing context** | Prior attempts, rejected approaches, related work, why they failed |
58
+ | **Terminology** | Ambiguous or overloaded words. Pin every term that has two plausible meanings |
59
+ | **Verification & rollout** | Tests, UAT, review, migration, communication, who signs off |
60
+
61
+ ### 3. Ask in the right order — broad to narrow
62
+
63
+ 1. **Purpose and scope first.** Answers here collapse whole branches of later questions.
64
+ 2. **Then success criteria and constraints** — they bound the solution space.
65
+ 3. **Then specifics** — inputs/outputs, edge cases, dependencies.
66
+ 4. **Then risks and verification** last, when you know enough to make them concrete.
67
+
68
+ Never open with detail questions while the purpose is still fuzzy.
69
+
70
+ ### 4. Question craft — what makes a question good
71
+
72
+ | Principle | Do | Don't |
73
+ |-----------|----|-------|
74
+ | **Open before closed** | "What does success look like for this?" to surface unknowns, then closed questions to pin them | Start with yes/no questions that presuppose your own framing |
75
+ | **One concept per question** | Split compound questions; each answer maps to one decision | "Should it be fast, cached, and paginated?" |
76
+ | **Concrete over abstract** | Offer a specific scenario or example: "If the input is empty, should it error or return `[]`?" | "How should edge cases be handled?" |
77
+ | **Offer options with a recommendation** | 2-4 distinct choices, your recommended one first with the reason; the user can always type something else | Unbounded questions when you already have a sensible default |
78
+ | **Neutral, non-leading** | Present alternatives fairly | Smuggle your preferred answer into the phrasing |
79
+ | **Expose assumptions** | State your assumption and ask the user to confirm or correct it: "I'm assuming X because Y — right?" | Silently building on an unverified assumption |
80
+ | **Probe the "why"** | Follow a stated requirement with "what's that protecting against?" to find the real need | Accepting a solution-shaped answer as the requirement |
81
+ | **Test with contrasts** | "What would make you reject this result?" / "What's the opposite of what you want?" | Only asking about the happy path |
82
+ | **Short and self-contained** | The user may see only the question; include the context it depends on | Referencing earlier text the user can't see |
83
+
84
+ ### 5. Follow-up discipline — the Socratic core
85
+
86
+ An answer is not accepted until it clears the bar. After each answer, run these checks and **follow up on any that fail**:
87
+
88
+ | Check | Follow-up when it fails |
89
+ |-------|------------------------|
90
+ | **Vague** ("fast", "clean", "soon", "users", "etc.") | Ask for a number, a name, a threshold, an example |
91
+ | **Solution disguised as a requirement** | Ask what problem that solution solves; confirm the problem, then the approach |
92
+ | **Contradicts an earlier answer, the code, or the wiki** | Surface the conflict verbatim and ask which holds; never silently pick |
93
+ | **Introduces a new term or dependency** | Add it to the doubt inventory and probe it |
94
+ | **"I don't know" / "whatever you think"** | Offer 2-3 concrete options with a recommendation and the consequence of each; record the user's pick (or explicit delegation) as a decision |
95
+ | **Reveals a new branch** | Add the branch's questions to the inventory; ask them before moving on |
96
+ | **Too easy / too agreeable** | Test it: ask what would make the user change their mind, or probe the counter-case |
97
+
98
+ Use the user's answers to **generate the next question** — do not march through a fixed script. Each round should be informed by everything learned so far.
99
+
100
+ ### 6. Batching and tooling
101
+
102
+ - Use `AskUserQuestion` for choices (1-4 questions per call, 2-4 options each, recommended option first with "(Recommended)"). Free-text "Other" is always available to the user.
103
+ - Batch **independent** questions in one round; keep **dependent** questions sequential (the answer to one decides the next).
104
+ - Prefer several focused rounds over one overwhelming wall of questions, but never stop early to be polite: **thoroughness beats brevity here.**
105
+ - If `AskUserQuestion` is unavailable (headless, subagent, or non-interactive run), do **not** guess. Return the numbered question list to your caller as your result and stop — an unanswered doubt must block the work, not be papered over.
106
+
107
+ ### 7. The exit gate — when you may stop asking
108
+
109
+ You may stop only when **all** of these hold:
110
+
111
+ - [ ] Every row of the doubt inventory is resolved, or the user explicitly declared it out of scope / delegated it.
112
+ - [ ] You could explain the task to a colleague with no context and they'd build the right thing.
113
+ - [ ] You can state the success criteria as observable checks.
114
+ - [ ] You can list the non-goals and the things that must not happen.
115
+ - [ ] No answer is vague, contradictory, or unverified.
116
+ - [ ] Asking one more question would yield only noise (the answer wouldn't change what you build).
117
+
118
+ The last item is the guard against interrogating forever: exhaustive means *no material doubt remains*, not *every conceivable question was asked*. If a question's answer would not change the work, drop it.
119
+
120
+ ### 8. Play it back and get explicit confirmation
121
+
122
+ Before any work begins, present a **Shared Understanding Summary** as a table and ask for confirmation via `AskUserQuestion` (*Confirmed — proceed* / *Needs correction* / *Cancel*):
123
+
124
+ | Section | Content |
125
+ |---------|---------|
126
+ | **Task** | One-paragraph restatement in your own words |
127
+ | **Purpose** | The why |
128
+ | **In scope** | Bulleted deliverables |
129
+ | **Out of scope** | Explicit non-goals |
130
+ | **Success criteria** | Observable checks |
131
+ | **Constraints** | With sources |
132
+ | **Decisions made** | Each Q → A, including options the user delegated |
133
+ | **Assumptions** | Anything still assumed, each with *impact if wrong* |
134
+ | **Open items** | Anything intentionally deferred, with an owner |
135
+
136
+ Corrections loop back to Step 5. **Do not start the task until the user confirms.** Once confirmed, hand the summary to the next step (or to subagents as their brief) and proceed.
137
+
138
+ ---
139
+
140
+ ## Anti-patterns
141
+
142
+ | Anti-pattern | Why it fails |
143
+ |--------------|--------------|
144
+ | Asking what the code/wiki/memory already answers | Wastes the user's time; signals you didn't look |
145
+ | Guessing to avoid "bothering" the user | Silent assumptions are the main source of rework |
146
+ | Interrogation without synthesis (rapid-fire, no playback) | User can't tell if you understood; errors survive |
147
+ | Leading questions | Produces confirmation of your bias, not the user's intent |
148
+ | Compound questions | Ambiguous answers; one half gets dropped |
149
+ | Accepting vague answers to keep momentum | Defers the ambiguity into the implementation |
150
+ | Starting work "while waiting" on answers | Anchors on an unconfirmed reading and wastes effort |
151
+ | Endless questioning past the exit gate | Exhaustive ≠ infinite; stop when answers can't change the outcome |
152
+ | Asking process questions the user can't answer ("which design pattern?") when they care about outcomes | Ask about behavior and goals; propose the technical choice yourself |
153
+
154
+ ## CRITICAL rules
155
+
156
+ 1. **Ground first, ask second.** Never ask a question you can answer by reading the repo, wiki, memory, or conversation.
157
+ 2. **No work before the exit gate.** Do not write code, files, or plans until the Step 7 checklist is satisfied and the Step 8 summary is confirmed.
158
+ 3. **Never invent answers.** Every decision in the summary comes from the user (or an explicit delegation recorded as such).
159
+ 4. **Follow up on every weak answer** — vague, contradictory, solution-shaped, or unverified answers are not accepted.
160
+ 5. **Recommend, don't just survey.** Offer options with a recommended default so the user can decide quickly.
161
+ 6. **Surface contradictions verbatim** — never silently resolve a conflict between answers, code, or docs.
162
+ 7. **Blocked means blocked.** If you cannot ask (non-interactive context), return the open questions to the caller instead of proceeding on assumptions.
163
+ 8. **Write nothing by default.** This skill produces understanding, not files; only persist the summary if the user asks (and then to the location they name, respecting the two-domain wiki rule).
@@ -203,7 +203,7 @@ Update the roadmap's `updated:` frontmatter field to today's date. Use `Read` th
203
203
 
204
204
  ### Step 12: Append to wiki/log.md
205
205
 
206
- Append:
206
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
207
207
 
208
208
  ```
209
209
  ## [YYYY-MM-DD] task | TASK-NNNN <task title>
@@ -266,7 +266,7 @@ If the file does not exist, create it with a `# UAT` heading and the list entry.
266
266
 
267
267
  ### Step 6: Append to wiki/log.md
268
268
 
269
- Append:
269
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
270
270
 
271
271
  ```
272
272
  ## [YYYY-MM-DD] uat | UAT-NNNN UAT: <task title>
@@ -48,8 +48,8 @@ Read the task file. Extract:
48
48
  - The file will have its status set to `skipped` in Step 3.
49
49
 
50
50
  **If no UAT file exists:**
51
- - Determine the next UAT-NNNN by reading `wiki/work/uat/index.md` (highest existing NNN + 1).
52
- - Derive the slug from the task title (lowercase, hyphens, strip special chars).
51
+ - **The UAT ID mirrors the task number** (TASK-0118 → UAT-0118; keep the task's digit width). Never allocate "highest existing + 1" and never read `uat/index.md` for a number — that desyncs UAT and task IDs when skips are batched. Slug mirrors the task slug.
52
+ - If a UAT file for that number already exists in `wiki/work/uat/` (or its `archive/`), treat it as the linked UAT instead of creating a new one.
53
53
  - Create `wiki/work/uat/UAT-NNNN-slug.md` using this skeleton:
54
54
 
55
55
  ```markdown
@@ -73,8 +73,7 @@ updated: YYYY-MM-DD
73
73
  This task's UAT was intentionally skipped. No test cases were generated or executed.
74
74
  ```
75
75
 
76
- - Add a row to `wiki/work/uat/index.md`:
77
- `| UAT-NNNN | <title> | skipped | <TASK-NNNN> |`
76
+ - Do **not** add a row to `wiki/work/uat/index.md` — the skeleton is born terminal, so it never enters the active index. Skip the UAT index-row removal in Step 3 as well.
78
77
 
79
78
  ---
80
79
 
@@ -85,7 +84,7 @@ Apply the STATUS-FLIP PROCEDURE to both artifacts:
85
84
  **UAT file** (`wiki/work/uat/UAT-NNNN-slug.md`):
86
85
  1. Edit `status: pending` (or whatever current status) → `status: skipped`
87
86
  2. Edit `updated:` → today's date
88
- 3. Remove the UAT's row from `wiki/work/uat/index.md` (skipped UATs are not active)
87
+ 3. Remove the UAT's row from `wiki/work/uat/index.md` (skipped UATs are not active) — only when the UAT file already existed
89
88
 
90
89
  **Task file** (`wiki/work/tasks/TASK-NNNN-slug.md`):
91
90
  1. Edit `status:` (whatever it currently is — `todo`, `in-progress`, or `pending-uat`) → `status: done`
@@ -111,32 +110,30 @@ Use `Bash` for `git mv` only. Use `Edit` for all index appends.
111
110
 
112
111
  ## Step 4: Roadmap Auto-Checkoff
113
112
 
114
- Scan every active roadmap (files in `wiki/work/roadmaps/` whose `status: active` frontmatter):
113
+ Flip only **this task's own** checkbox. Do not read every roadmap and do not touch other tasks' lines.
115
114
 
116
- 1. Use Serena `list_dir` on `wiki/work/roadmaps/` (exclude `lifecycle.md` and `index.md`).
117
- 2. Read each file. Look for lines matching `- [ ] [[TASK-NNNN` (wiki-style task link).
118
- 3. For each match, `Edit` `- [ ] [[TASK-NNNN` → `- [x] [[TASK-NNNN` **and** update `updated:` in that roadmap's frontmatter to today.
119
- 4. **Phase sweep**: after flipping this task's line, scan other `- [ ] [[TASK-NNNN` lines in the same `## Phase` block. For each, check if that task's `status:` is `done`. If yes, flip `- [ ]` → `- [x]`.
120
- 5. **Roadmap completion check**: if ALL checkboxes in the roadmap are now `[x]`, close it in place — read `~/.claude/skills/_shared/ARCHIVE-WORK-ITEM.md` and run its **In-place close (roadmaps, decisions, requirements)** section with `family: roadmaps`, `terminal_status: done`, `log: skip` (Step 6 writes this skill's own log entry). The file is not moved; its `status:` flips to `done` and its row moves from `## Active` to `## Closed` in `wiki/work/roadmaps/index.md`.
121
- 6. Silent no-op if no roadmap references this task.
115
+ 1. One Serena `search_for_pattern` over `wiki/work/roadmaps/` (skip `archive/`, `index.md`, `lifecycle.md`) for `- \[ \] \[\[TASK-NNNN`. No match → silent no-op, go to Step 5.
116
+ 2. For each roadmap returned: `Read` it, `Edit` `- [ ] [[TASK-NNNN` → `- [x] [[TASK-NNNN`, and update its `updated:` to today. Skip any roadmap whose `status:` is not `active`.
117
+ 3. **Completion check**: if every checkbox in that roadmap is now `[x]`, close it in place — run `~/.claude/skills/_shared/ARCHIVE-WORK-ITEM.md` **In-place close** with `family: roadmaps`, `terminal_status: done`, `log: skip` (Step 6 writes this skill's log entry).
118
+
119
+ Other tasks' checkboxes are reconciled by `/roadmap-next` and `/task-assess`, not here.
122
120
 
123
121
  ---
124
122
 
125
123
  ## Step 5: Decision Annotation
126
124
 
127
- Check the task body for a typed link `implements::[[ADR-NNNN#DM]]` (or legacy `implements::[[DEC-NNNN#DM]]`) or similar decision reference:
125
+ Use the task body already read in Step 1. **Only if** it contains `implements::[[ADR-NNNN#DM]]` (or legacy `implements::[[DEC-NNNN#DM]]`):
128
126
 
129
- - If found, locate the decision file in `wiki/work/decisions/`.
130
- - Search the decision file for any `Source task(s):` line referencing this task.
127
+ - Resolve that decision file (ID-RESOLUTION, family: decisions) and `search_for_pattern` within that one file for a `Source task(s):` line naming this task.
131
128
  - If found, append ` — done (UAT skipped) YYYY-MM-DD` to that line.
132
- - Use Serena `search_for_pattern` on `wiki/work/decisions/` for the task ID to catch any reference pattern.
133
- - If not found: skip silently.
129
+
130
+ No such link → skip with zero tool calls. Never search `wiki/work/decisions/` as a whole.
134
131
 
135
132
  ---
136
133
 
137
134
  ## Step 6: Log Entry
138
135
 
139
- Append to `wiki/log.md`:
136
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
140
137
 
141
138
  ```markdown
142
139
  ## [YYYY-MM-DD] uat | UAT-NNNN skipped → TASK-NNNN done · both archived
@@ -150,16 +147,9 @@ Use the `Edit` tool (append at end of file).
150
147
 
151
148
  ## Step 7: Report Completion
152
149
 
150
+ Two lines at most, no banner, no per-step narration:
151
+
153
152
  ```
154
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
155
- UAT SKIP COMPLETE
156
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
157
- Task: TASK-NNNN → status: done → archived to tasks/archive/
158
- UAT: UAT-NNNN → status: skipped → archived to uat/archive/
159
- (or: Skeleton UAT-NNNN created and immediately archived)
160
-
161
- Roadmaps updated: [list or "None"]
162
- Decisions updated: [list or "None"]
163
- Log entry appended.
164
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
153
+ TASK-NNNN → done, UAT-NNNN → skipped (both archived).
154
+ Roadmaps: <IDs or none> · Decisions: <IDs or none>
165
155
  ```
@@ -171,7 +171,7 @@ Runs once no test has a blocking status. Two outcomes.
171
171
  - `git mv wiki/work/tasks/<TASK>.md wiki/work/tasks/archive/` → append `| [[TASK-NNNN]] | Title | done | YYYY-MM-DD |` to `wiki/work/tasks/archive/index.md`
172
172
  5. **Roadmap auto-checkoff** — scan `wiki/work/roadmaps/` for `status: active` files. For each: Edit `- [ ] [[TASK-NNNN` → `- [x] [[TASK-NNNN`; then sweep remaining `- [ ]` free-text lines, checking the ones the completing task clearly accomplished (leave uncertain ones). If all items are now `[x]`: close the roadmap in place — read `~/.claude/skills/_shared/ARCHIVE-WORK-ITEM.md` and run its **In-place close (roadmaps, decisions, requirements)** section with `family: roadmaps`, `terminal_status: done` (status flip, `## Active` → `## Closed` index row move; no `git mv`, no `archive/`). Silent no-op if no roadmap references the task. `Edit` only (except the task/UAT `git mv` above).
173
173
  6. **Decision annotation** — check the task body for `implements::[[ADR-NNNN#DM]]` (or legacy `implements::[[DEC-NNNN#DM]]`). If found: open the decision file in `wiki/work/decisions/` (`ADR-NNNN-slug.md`, or legacy `DEC-NNNN-slug.md`), append `— implemented YYYY-MM-DD` to this task's `Source task(s):` line. Then check `wiki/work/tasks/` **and** `tasks/archive/` for other `todo|in-progress` tasks with the same `implements::[[ADR-NNNN#DM]]` (either prefix form); if none remain, append `— decision fully implemented YYYY-MM-DD` on a new line in the `## DM.` block. Sweep remaining `- [ ]` items in that block, checking the ones this task accomplished. `Read` then `Edit` only — never `sed`.
174
- 7. **Log entry** — append to `wiki/log.md`:
174
+ 7. **Log entry** — follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
175
175
  ```
176
176
  ## [YYYY-MM-DD] uat | UAT-NNNN passed<MODE-TAG> · TASK-NNNN done
177
177
  Archived UAT-NNNN → uat/archive/ and TASK-NNNN → tasks/archive/. [one sentence on what was verified]
@@ -67,7 +67,7 @@ Read `~/.claude/skills/_shared/ARCHIVE-WORK-ITEM.md` now and run its Procedure o
67
67
 
68
68
  ## Step 5: Update wiki/log.md
69
69
 
70
- Append one entry:
70
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
71
71
  ```
72
72
  ## [YYYY-MM-DD] archive | <family> — N items archived
73
73
  Moved N terminal items from wiki/work/<family>/ to wiki/work/<family>/archive/. IDs: TASK-023, TASK-031, …
@@ -102,7 +102,7 @@ Use a single `Edit` call per section.
102
102
 
103
103
  ## Step 7: Append to the Log
104
104
 
105
- Append to `wiki/log.md`:
105
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
106
106
  ```
107
107
  ## [YYYY-MM-DD] ingest | <source title>
108
108
  Ingested from raw/<filename>. Key claims: [2–3 bullet summary]. [N] entity pages touched, [M] concept pages touched.
@@ -161,7 +161,7 @@ Ask: **"Which findings should I fix?"** — wait for the user's reply before mak
161
161
 
162
162
  ## Step 5: Apply approved fixes only
163
163
 
164
- For each approved fix, apply it with a single `Edit` call. After all fixes, append one log entry to `wiki/log.md`:
164
+ For each approved fix, apply it with a single `Edit` call. After all fixes, follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
165
165
  ```
166
166
  ## [YYYY-MM-DD] lint | <N> issues found, <M> fixed
167
167
  Summary of findings and fixes applied.
@@ -96,7 +96,7 @@ If the user says yes:
96
96
  1. Create `wiki/knowledge/concepts/<concept-slug>.md` with proper frontmatter (`id`, `title`, `updated`, `tags`, `sources` if derived from a raw source).
97
97
  2. Add a typed link `derived_from::[[source-slug]]` if the answer came from an ingested source.
98
98
  3. Add the new page to the **Concepts** section of `wiki/index.md`.
99
- 4. Append to `wiki/log.md`: `## [YYYY-MM-DD] query | <question summary>\nFiled answer as wiki/knowledge/concepts/<slug>.md.`
99
+ 4. Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to `## [YYYY-MM-DD] query | <question summary>\nFiled answer as wiki/knowledge/concepts/<slug>.md.`
100
100
  5. **Only on this filing path** (never on the read-only answer path): 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 the newly filed page under Recent Changes. Do not restate the procedure here; follow it as written. Step 4's ingests refresh the hot cache on their own as part of the `/wiki-ingest` procedure — that is a write path, not the read-only answer path.
101
101
 
102
102
  ---