@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.
- package/README.md +1 -0
- package/lib/scripts/README.md +4 -3
- package/lib/scripts/bootstrap-prefs.js +25 -2
- package/lib/scripts/git-prefs.js +123 -0
- package/lib/scripts/install-global.sh +3 -0
- package/lib/scripts/merge-gitignore.sh +11 -5
- package/lib/scripts/rename-wiki-ids.js +2 -2
- package/lib/scripts/sync-wiki-scaffold.sh +24 -11
- package/lib/scripts/templates/CLAUDE-prose-style.md +22 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
- package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
- package/lib/scripts/templates/guides/stubs/serena.md +4 -1
- package/lib/scripts/templates/wiki/conventions.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +1 -1
- package/lib/skills/README.md +2 -1
- package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +2 -2
- package/lib/skills/_shared/ID-RESOLUTION.md +2 -2
- package/lib/skills/_shared/LOG-APPEND.md +34 -0
- package/lib/skills/_shared/SKILL-BOILERPLATE.md +1 -1
- package/lib/skills/adr-create/SKILL.md +2 -2
- package/lib/skills/adr-deprecate/SKILL.md +1 -1
- package/lib/skills/adr-extract/SKILL.md +1 -1
- package/lib/skills/adr-finalize/SKILL.md +2 -1
- package/lib/skills/autopilot/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +1 -1
- package/lib/skills/bug-triage/SKILL.md +1 -1
- package/lib/skills/git-commit/SKILL.md +18 -27
- package/lib/skills/prd-create/SKILL.md +2 -2
- package/lib/skills/prd-deprecate/SKILL.md +1 -1
- package/lib/skills/prd-finalize/SKILL.md +1 -1
- package/lib/skills/socratic-qa/SKILL.md +163 -0
- package/lib/skills/task-create/SKILL.md +1 -1
- package/lib/skills/uat-create/SKILL.md +1 -1
- package/lib/skills/uat-skip/SKILL.md +19 -29
- package/lib/skills/uat-walk/UAT-CORE.md +1 -1
- package/lib/skills/wiki-archive/SKILL.md +1 -1
- package/lib/skills/wiki-ingest/SKILL.md +1 -1
- package/lib/skills/wiki-lint/SKILL.md +1 -1
- package/lib/skills/wiki-query/SKILL.md +1 -1
- package/lib/skills/wiki-rotate-log/SKILL.md +14 -24
- package/lib/skills/wiki-tidy/SKILL.md +5 -12
- 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
|
|
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.**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
69
|
+
```bash
|
|
70
|
+
node ~/.claude/git-prefs.js
|
|
71
|
+
```
|
|
74
72
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
52
|
-
-
|
|
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
|
-
-
|
|
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
|
-
|
|
113
|
+
Flip only **this task's own** checkbox. Do not read every roadmap and do not touch other tasks' lines.
|
|
115
114
|
|
|
116
|
-
1.
|
|
117
|
-
2.
|
|
118
|
-
3.
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
133
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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** —
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
21
|
-
- If line count is **
|
|
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:
|
|
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
|
-
|
|
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
|
|
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.
|