@codewizard-dt/bootstrap 6.0.1 → 6.2.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 (42) hide show
  1. package/README.md +1 -0
  2. package/lib/scripts/README.md +4 -3
  3. package/lib/scripts/bootstrap-prefs.js +25 -2
  4. package/lib/scripts/git-prefs.js +123 -0
  5. package/lib/scripts/install-global.sh +3 -0
  6. package/lib/scripts/merge-gitignore.sh +11 -5
  7. package/lib/scripts/rename-wiki-ids.js +2 -2
  8. package/lib/scripts/sync-wiki-scaffold.sh +24 -11
  9. package/lib/scripts/templates/CLAUDE-prose-style.md +22 -0
  10. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  11. package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
  12. package/lib/scripts/templates/guides/stubs/serena.md +4 -1
  13. package/lib/scripts/templates/wiki/conventions.md +1 -1
  14. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +1 -1
  15. package/lib/skills/README.md +2 -1
  16. package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +2 -2
  17. package/lib/skills/_shared/ID-RESOLUTION.md +2 -2
  18. package/lib/skills/_shared/LOG-APPEND.md +34 -0
  19. package/lib/skills/_shared/SKILL-BOILERPLATE.md +1 -1
  20. package/lib/skills/adr-create/SKILL.md +2 -2
  21. package/lib/skills/adr-deprecate/SKILL.md +1 -1
  22. package/lib/skills/adr-extract/SKILL.md +1 -1
  23. package/lib/skills/adr-finalize/SKILL.md +2 -1
  24. package/lib/skills/autopilot/SKILL.md +1 -1
  25. package/lib/skills/bug-assess/SKILL.md +1 -1
  26. package/lib/skills/bug-triage/SKILL.md +1 -1
  27. package/lib/skills/git-commit/SKILL.md +18 -27
  28. package/lib/skills/prd-create/SKILL.md +2 -2
  29. package/lib/skills/prd-deprecate/SKILL.md +1 -1
  30. package/lib/skills/prd-finalize/SKILL.md +1 -1
  31. package/lib/skills/socratic-qa/SKILL.md +163 -0
  32. package/lib/skills/task-create/SKILL.md +1 -1
  33. package/lib/skills/uat-create/SKILL.md +1 -1
  34. package/lib/skills/uat-skip/SKILL.md +19 -29
  35. package/lib/skills/uat-walk/UAT-CORE.md +1 -1
  36. package/lib/skills/wiki-archive/SKILL.md +1 -1
  37. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  38. package/lib/skills/wiki-lint/SKILL.md +1 -1
  39. package/lib/skills/wiki-query/SKILL.md +1 -1
  40. package/lib/skills/wiki-rotate-log/SKILL.md +14 -24
  41. package/lib/skills/wiki-tidy/SKILL.md +5 -12
  42. package/package.json +1 -1
@@ -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
  ---
@@ -1,13 +1,15 @@
1
1
  ---
2
2
  name: wiki-rotate-log
3
- description: Rotate wiki/log.md into a timestamped archive file when it grows past ~500 lines; create a fresh log.md with an archive-pointer header
3
+ description: Rotate wiki/log.md into a timestamped archive file when it grows past 200 lines; create a fresh log.md with an archive-pointer header. Forced, not a nudge — no confirmation is asked.
4
4
  category: wiki
5
5
  model: claude-sonnet-5
6
6
  ---
7
7
 
8
8
  # Wiki Rotate Log
9
9
 
10
- Rotate `wiki/log.md` into a timestamped archive file (`log-YYYY_MM_DD_HHMMSS.md`) when it exceeds ~500 lines. Create a fresh `log.md` with an archive-pointer header. **Never truncate** — all content moves to the timestamped file.
10
+ Rotate `wiki/log.md` into a timestamped archive file (`log-YYYY_MM_DD_HHMMSS.md`) when it reaches **200 lines**. Create a fresh `log.md` with an archive-pointer header. **Never truncate** — all content moves to the timestamped file.
11
+
12
+ **This is forced, not advisory.** At or above the threshold, rotation happens — it is never a question put to the user ("rotate now?", "proceed anyway?"). This is also the canonical rotation mechanic other skills defer to (`lib/skills/_shared/LOG-APPEND.md` runs Steps 2 and 4 below as part of every log append, unconditionally, whenever any skill's append would otherwise push the file over threshold) — do not duplicate these steps elsewhere; point at this file instead.
11
13
 
12
14
  The timestamp (to the second) makes every archive filename unique by construction, so repeated rotations never collide — no half-year or sequence-suffix logic needed.
13
15
 
@@ -17,8 +19,8 @@ The timestamp (to the second) makes every archive filename unique by constructio
17
19
 
18
20
  Read `wiki/log.md`. Count the total number of lines.
19
21
 
20
- - If line count is **under 500**: report the count and warn the user: "The log has N lines — rotation is recommended at ~500. Proceed anyway? (yes / no)"
21
- - If line count is **500 or more**: proceed directly.
22
+ - If line count is **under 200**: report the count ("Log has N lines — under the 200-line rotation threshold, nothing to do.") and stop. No question is asked.
23
+ - If line count is **200 or more**: proceed directly to Step 2 — forced, no confirmation.
22
24
 
23
25
  ## Step 2: Determine the archive filename
24
26
 
@@ -26,24 +28,9 @@ Generate a timestamp to the second using Bash: `date +%Y_%m_%d_%H%M%S`.
26
28
 
27
29
  The archive filename is `log-<timestamp>.md` — e.g. `log-2026_06_14_153012.md`. Because the timestamp is unique to the second, no collision check or suffix logic is needed.
28
30
 
29
- ## Step 3: Confirm with the user
30
-
31
- Show the plan:
32
- ```
33
- Log rotation plan:
34
- Current: wiki/log.md (N lines)
35
- Archive: wiki/log-2026_06_14_153012.md
36
- New log: wiki/log.md (empty, with archive pointer)
37
-
38
- The existing log.md will be renamed — no content is deleted.
39
- Proceed? (yes / no)
40
- ```
41
-
42
- Wait for confirmation.
31
+ ## Step 3: Rotate (forced — no confirmation)
43
32
 
44
- ## Step 4: Rotate
45
-
46
- 1. **Rename** `wiki/log.md` → `wiki/log-<timestamp>.md` using Bash `mv`.
33
+ 1. **Rename** `wiki/log.md` → `wiki/log-<timestamp>.md` using Bash `git mv` (plain `mv` only when the project is not a git repo).
47
34
  2. **Check** for any existing archive pointers in the old log (lines starting with `> Archives:`). If present, carry them forward into the new log.
48
35
  3. **Create** a new `wiki/log.md` with:
49
36
 
@@ -66,25 +53,28 @@ Operations: `scaffold`, `ingest`, `query`, `lint`, `decision`, `task`, `bug`, `r
66
53
  ---
67
54
 
68
55
  ## [YYYY-MM-DD] rotate | log.md rotated — N lines archived to log-<timestamp>.md
69
- Previous log archived to log-<timestamp>.md. Fresh log started.
56
+ Previous log archived to log-<timestamp>.md (forced rotation at the 200-line threshold). Fresh log started.
70
57
  ```
71
58
 
72
59
  Replace `<timestamp>` with the actual timestamp and `N` with the entry count. The `[YYYY-MM-DD]` date prefix on the rotation entry stays date-only (matching all other log entries) — only the archive filename carries the full timestamp. If there were prior archive pointers, add them to the `> Archives:` line separated by ` · `.
73
60
 
74
- ## Step 5: Report
61
+ ## Step 4: Report
75
62
 
76
63
  Confirm rotation is complete:
77
64
  ```
78
- Done. wiki/log.md rotated:
65
+ Done. wiki/log.md rotated (forced, 200-line threshold reached):
79
66
  - N lines moved to wiki/log-2026_06_14_153012.md
80
67
  - New wiki/log.md created with archive pointer
81
68
  ```
82
69
 
70
+ When invoked by `lib/skills/_shared/LOG-APPEND.md` as part of another skill's append, this report is folded into that skill's own summary rather than shown standalone — say in one line that a forced rotation occurred, then continue with the caller's own report.
71
+
83
72
  ---
84
73
 
85
74
  ## CRITICAL rules
86
75
 
87
76
  - **Never delete** any log content — rotation is renaming + creating a new file.
88
77
  - **Never edit** the archived file after renaming.
78
+ - **Never ask for confirmation** at or above the threshold. Rotation is forced; the only non-rotating outcome is being under threshold, which needs no question either.
89
79
  - The `> Archives:` header line in the new `log.md` must link to ALL prior archive files, not just the most recent one.
90
80
  - The first entry in the new `log.md` must be the rotation event itself.