SKILL.md-Sanierung: Checklisten, Kommandolisten, wiki-status-Hard-Rule, wiki-query-Filingpruefung (schliesst #70, #74, #75, #78)

Files changed: - CHANGES.md - VERSION - instructions/CONTRACT.md - instructions/wiki-ingest/SKILL.md - instructions/wiki-lint/SKILL.md - instructions/wiki-manage/SKILL.md - instructions/wiki-query/SKILL.md - instructions/wiki-status/SKILL.md
2026-09-09 17:01:42 +02:00
parent 663b1c046c
commit 11d64e6aa0
8 changed files with 222 additions and 23 deletions
@@ -217,6 +217,29 @@ reads, and no tool hook is wired on the primary harness at all - so a `head -100
 to score. The other half of the claim, what ended up in the context window, produces no event
 anywhere by construction. Gitea #72 records what a test would cost and why it was not bought.

+### When a skill carries a copy-in checklist
+
+Anthropic's skill-authoring guidance suggests, for a "particularly complex workflow", a checklist
+the agent copies into its response and ticks off as it goes. It names no threshold, so this repo
+sets one - otherwise the two skills that have such a block and the three that do not read as an
+accident rather than a decision.
+
+A `SKILL.md` carries the block when **one** of its flows runs to eight steps or more *and* that
+flow contains steps whose omission is silent - a judgment call, a field filled by hand, a
+cadence check, anything no tool error and no validator would report missing. Both halves are
+required. Length alone is not the problem: a long flow of tool calls announces its own gaps,
+because the next call fails without the previous one.
+
+Two skills qualify today, and the block names each of their numbered steps once, verbatim:
+`wiki-ingest` (twelve steps, of which `## Not Extracted` in step 6, the coverage check in step 10
+and the lint cadence in step 12 all fail quietly) and `wiki-lint` (nine, with steps 3-6 pure
+judgment). The other three do not, and the reason is worth stating so nobody adds one out of
+symmetry: `wiki-manage` has two flows of seven, `wiki-query` six, `wiki-status` five, and none of
+them is long enough for a reader to lose the thread.
+
+The block says that it is to be copied and carried, not read. A checklist read once is the table
+of contents it replaced.
+
 ### How much reasoning a step may carry

 "Cut the reasoning" and "keep enough to decide an edge case" are one sentence pulling two ways,
@@ -16,6 +16,27 @@ Contracts are read **when the step needs them**, not upfront: a source that prod
 pages should never have cost the concept contract. Field-level requirements always come from
 `tools/wikitool types describe <type>`, never from memory.

+## Run checklist
+
+Copy this block into your first reply of the run and tick each line as you reach it. It is
+carried through the run, not read once: several steps below fail silently - nothing errors, no
+validator complains - and the ticked list is the only record that they happened.
+
+```markdown
+- [ ] 1. Promote from `incoming/` if that is where the file sits
+- [ ] 2. Read the source
+- [ ] 3. Extract metadata
+- [ ] 4. Check what the wiki already knows
+- [ ] 5. Discuss with the user
+- [ ] 6. Create the source page (incl. `## Not Extracted`)
+- [ ] 7. Create or update entity pages
+- [ ] 8. Create or update concept pages
+- [ ] 9. Cross-reference
+- [ ] 10. Check coverage
+- [ ] 11. Close out
+- [ ] 12. Check the lint cadence
+```
+
 ## Steps

 1. **Promote from `incoming/` if that is where the file sits.** Read
@@ -201,9 +222,9 @@ pages should never have cost the concept contract. Field-level requirements alwa

 ## wikitool commands used

-`raw accept`, `search`, `new source`, `new entity`, `new concept`, `touch`, `xref add`,
-`xref link-source`, `sources coverage`, `sources rebuild-index`, `index rebuild`, `log append`,
-`log status`, `publish`
+`raw accept`, `search`, `types describe`, `new source`, `new entity`, `new concept`, `touch`,
+`cite add`, `xref add`, `xref link-source`, `sources coverage`, `sources rebuild-index`,
+`index rebuild`, `log append`, `log status`, `publish`

 ## Output

@@ -13,6 +13,24 @@ never something an agent has to remember.

 **Before the first `wikitool` call:** [session-setup.md](../session-setup.md).

+## Run checklist
+
+Copy this block into your first reply of the pass and tick each line as you reach it. Steps 3-6
+are pure judgment: nothing errors when they are skipped, and a pass that quietly ran only its
+mechanical half looks exactly like a complete one.
+
+```markdown
+- [ ] 1. Structural scan
+- [ ] 2. Raw coverage
+- [ ] 3. Contradictions (judgment)
+- [ ] 4. Stale claims (judgment)
+- [ ] 5. Missing pages (judgment)
+- [ ] 6. Duplicated rules (judgment)
+- [ ] 7. Repair what is mechanical
+- [ ] 8. Refresh confidence and verify the stack
+- [ ] 9. Rebuild, write the report, carry its findings out
+```
+
 ## Steps

 1. **Structural scan.**
@@ -119,9 +137,13 @@ never something an agent has to remember.

 ## wikitool commands used

-`lint`, `lint --markdown`, `search`, `log status`, `sources coverage`, `xref remove`, `rename`,
-`rm`, `new`, `confidence decay --apply`, `confidence init-base --apply`, `docs verify`,
-`instructions verify`, `sources rebuild-index`, `index rebuild`, `log append`
+`lint`, `search`, `sources coverage`, `xref add`, `xref remove`, `rename`, `new`,
+`confidence decay --apply`, `confidence init-base --apply`, `docs verify`, `instructions verify`,
+`sources rebuild-index`, `index rebuild`, `log append`, `publish` (only if asked)
+
+**Deliberately absent:** `rm` - a lint pass never deletes a page, and
+[page-lifecycle.md](../page-lifecycle.md) is where a deletion belongs. `log status` - it decides
+this skill's *trigger*, but `wiki-ingest`'s last step is what runs it.

 ## Output

@@ -102,9 +102,17 @@ page, so none of it is a file operation.

 ## wikitool commands used

-`search`, `types list`, `types describe`, `new`, `touch`, `xref add`, `xref remove`,
+`search`, `types list`, `types describe`, `new`, `touch`, `cite add`, `xref add`, `xref remove`,
 `sources rebuild-index`, `index rebuild`, `log append`, `publish`

+`xref remove` belongs to the unlinking case, which this skill delegates whole to
+[page-lifecycle.md](../page-lifecycle.md) rather than describing in a step of its own.
+
 ## Output

 A new or updated page, published to `origin/main`.
+
+**Example triggers:**
+
+- "Create a concept page for the deployment pipeline we just discussed"
+- "Update the Index Scaling page with what the new lint run showed"
@@ -9,9 +9,11 @@ description: Answer a question using the LLM wiki's compiled knowledge - read-on

 **Trigger:** User asks a question.

+**Before the first `wikitool` call:** [session-setup.md](../session-setup.md).
+
 **Hard rule:** read-only with respect to wiki *content*. Never modify, hand-edit, or scaffold a
-page while answering. Two exceptions, both mechanical: step 5 (filing a valuable answer through
-`wikitool new`, never by hand) and step 6 (one audit entry via `wikitool log append`). If the
+page while answering. Two exceptions, both mechanical: step 6 (filing a valuable answer through
+`wikitool new`, never by hand) and step 7 (one audit entry via `wikitool log append`). If the
 wiki has no confident source, say so - per AGENTS.md's "never file an unsourced answer"
 invariant - rather than synthesizing a plausible-sounding answer from general knowledge.

@@ -46,12 +48,22 @@ invariant - rather than synthesizing a plausible-sounding answer from general kn
   Hedge to the page's confidence: below 0.6 write "possibly"/"may"; below 0.4 write
   "uncertain"/"unconfirmed".

-5. **File it back, if it earns a page.** Only when the answer required synthesis across several
-   pages, revealed something not already written down, and will be asked again. Then scaffold
-   it - `tools/wikitool new ...` - and follow `wiki-manage`. Never write the page by hand, and
-   never file an answer no source backs.
+5. **Decide what earns a page - before the first `new`.** Name every page you are considering,
+   then hold each one on its own against all three criteria: the answer required synthesis
+   across several pages, it revealed something not yet written down, and it will be asked
+   again. All three, per candidate. A batch is never judged as a batch - one page clearing the
+   bar says nothing about the next one.

-6. **Log it.**
+   A candidate that misses any of the three is not scaffolded. Put one line in the answer
+   naming what was considered and why it stays unwritten, and let the user ask for it anyway.
+   That is the whole cost of being wrong here in the cautious direction; the other direction is
+   a page nobody asked for, which reads exactly like a page the wiki needed and is far harder to
+   find again than a sentence in a chat log.
+
+6. **File back what survived.** Scaffold it - `tools/wikitool new ...` - and follow
+   `wiki-manage`. Never write the page by hand, and never file an answer no source backs.
+
+7. **Log it.**

   ```bash
   tools/wikitool log append --op query --title "<question>" --body "<outcome>"
@@ -65,12 +77,14 @@ invariant - rather than synthesizing a plausible-sounding answer from general kn
 - **Filed a page?** Query does **not** auto-publish. Run `tools/wikitool publish` only if asked;
  the sequence is in [publish-cycle.md](../publish-cycle.md).
 - **Several answers filed at once?** That can trip the Mass-Update Gate - see
-  [gates.md](../gates.md).
+  [gates.md](../gates.md). The gate is a brake, not the check: it counts files and knows nothing
+  about whether any of them earned a page. Step 5 is what decides that, and a batch small enough
+  to pass the gate has not been cleared by it.

 ## wikitool commands used

 `search`, `log append`. If filing an answer back: `new`, `xref add`, `sources rebuild-index`,
-`index rebuild`.
+`index rebuild`, and `publish` only if asked.

 ## Output

@@ -10,8 +10,12 @@ semantic review a lint pass does.

 **Trigger:** User asks for wiki statistics, "what's new", or a quick health snapshot.

-**Hard rule:** read-only. Never writes, scaffolds, or modifies any file. If something looks
-wrong, point the user at `wiki-lint` or `wiki-manage` instead of fixing it here.
+**Hard rule:** read-only with respect to wiki *content*. Never create, modify, or scaffold a
+page, never repair a finding, never publish. One file does get written: the report `lint`
+produces in step 2. That is not an exception being stretched - `reports/` is gitignored and holds
+no wiki page ([reports/CONTRACT.md](../../reports/CONTRACT.md)), so the write leaves nothing
+behind that the wiki ships. If something looks wrong, point the user at `wiki-lint` or
+`wiki-manage` instead of fixing it here.

 ## Steps

@@ -36,18 +40,23 @@ wrong, point the user at `wiki-lint` or `wiki-manage` instead of fixing it here.
 4. **Recent activity.** Read the last few entries of `kb/log.md`.

 5. **Summarize in chat.** Counts by type, N orphan pages, N uncovered raw files, most-connected
-   pages, and what changed recently. Do not write a report file - that is `wiki-lint`'s job.
+   pages, and what changed recently. Leave the step-2 report as `lint` left it: its "Semantic
+   Review" section stays empty and its findings are not carried into any page or into
+   `kb/log.md`. That is `wiki-lint`'s step 9, and it is what separates a snapshot from a pass.

 ## Decision points

 - **Findings worth acting on?** Point at `wiki-lint` (repairs) or `wiki-manage` (content). Do
  not fix anything here.
- **Never publishes** - nothing was written.
+- **Never publishes.** Nothing under `kb/` changed, and the step-2 report is gitignored, so
+  there is nothing a commit could pick up.

 ## wikitool commands used

-`lint` (no flags), `lint --json` (optional, for the link-graph data).
+`lint` (no flags).

 ## Output

 A short chat summary, plus a pointer to `wiki-lint` if deeper investigation is warranted.
+
+**Example trigger:** "Give me a quick wiki status"