The published skill collection had grown three naming shapes where it should have had three families. wiki-ingest/wiki-lint/wiki-manage/wiki-query/wiki-status and stack-dev/stack-close each named their domain; weekly-review named neither, and sat outside both.
Separately, all eight description: fields were written in the imperative ("Process a new source file…"), while Anthropic's skill-authoring guidance asks for third person, because the description is injected into the system prompt and an inconsistent point of view degrades skill selection.
Neither convention was written down anywhere, which is why the drift happened in the first place. Both are now fixed and documented.
Decisions (as implemented)
D1 - The new name is gtd-weekly-review, not wiki-review. Done.
GTD is a named, first-class layer in this stack, not a methodology label: the kb/gtd/ collection, the project type ("a committed initiative (a GTD project)"), wikitool review ("The GTD weekly review", tools/CONTRACT.md), the chemenu.tasks provider layer, .wikitool-tasks.json, and docs/knowledge-and-commitment.md. A wiki- prefix would have flattened that boundary.
D2 - The prefix names the subject domain, the directory names the distribution boundary. Done, and now written down.
Three families: wiki- (knowledge pipeline, under instructions/), gtd- (commitment layer, under instructions/), stack- (the stack itself, under instructions/dev/). instructions/CONTRACT.md § "Writing an instruction" gained a new subsection, "A skill's name declares its family", stating this - with the stack-dev/stack-close names themselves kept inside a <!-- dist:strip-start/end --> block, since CONTRACT.md ships to distributed instances and those two names would otherwise dangle past dist export.
D3 - No sibling gtd- skills created on spec. Held. Only gtd-weekly-review exists in the new family.
D4 - Version part: --patch, no --breaking. Done as planned. weekly-review was introduced by this same running candidate (never released), so no instance in the wild carried the old name - nothing to break. tools/wikitool version bump --patch on the 7.0.0 candidate produced 7.0.0-beta.8 → 7.0.0-beta.9; the bump still shows as boundary-crossing because the candidate already crossed earlier in the same run (project/kb/gtd/ adoption requirement) - the running candidate's compatibility state is max-wins and does not step back down for a later, non-crossing bump.
D5 - The historical 7.0.0-beta.8 bump-list title stayed as written. Done - it is machine-managed, dated evidence of what that bump actually did.
Third-person descriptions, decided during implementation, not originally scoped as its own decision: all eight skills' description: fields were rewritten from imperative to third person ("Processes...", "Answers...", "Switches...", etc.), matching Anthropic's guidance verbatim example ("Processes Excel files and generates reports"). instructions/CONTRACT.md gained a second new subsection, "A skill's description speaks in third person", noting this binds only instructions/<name>/SKILL.md - the flat instructions/<name>.md form keeps its existing imperative-title convention, since that description is read on demand rather than injected into the system prompt.
tools/wikitool instructions list names gtd-weekly-review, no weekly-review. instructions sync pruned both stale .agents/skills/weekly-review/ and .claude/skills/weekly-review/ (reported "removed 2 stale").
No file outside CHANGES.md and commonplace/ contains weekly-review as a skill name - swept after every edit; the only survivors are the dated CHANGES.md entries (7.0.0-beta.8's bump title/changeset, left per D5) and commonplace/kb/sources/koylanai-personal-brain-os.{md,json}, vendored third-party text about an unrelated npm run weekly-review script.
All eight published skills' description: are third person, still state what+when, all comfortably under 1024 characters.
instructions/CONTRACT.md § "Writing an instruction" carries both conventions, each once: "A skill's name declares its family" and "A skill's description speaks in third person" - both note nothing checks them mechanically.
Pulled through: AGENTS.md § Routing skill table, README.md (skill table row + the gtd-weekly-review mention in prose), INSTALL.md, instructions/setup-instance.md.
tools/wikitool docs verify, tools/wikitool instructions verify, and the full pytest suite (1383 tests) all pass. docs verify initially caught a real defect introduced during this work: the new "declares its family" prose named stack-dev/stack-close outside instructions/dev/ and outside a dist:strip block, which would have dangled in a distributed instance - fixed by wrapping those two names in <!-- dist:strip-start/end -->, matching the existing convention already used for the same names in AGENTS.md and README.md.
tools/wikitool version bump --patch made (7.0.0-beta.9), changeset prose written under ### Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions in CHANGES.md.
Published as commit 52ba5ba (tools/wikitool publish, cleared through the Mass-Update Gate at 17 files - the user approved the full file-and-line breakdown before --confirm).
Follow-up: the out-of-scope note was checked after all
The note below originally read "not moved here; worth its own issue if it's ever judged wrong". It was judged, immediately after closing, and it was wrong - so it was fixed in a second commit rather than left standing.
instructions/CONTRACT.md § "When a skill carries a copy-in checklist" counted "the two skills that have such a block and the three that do not" - five of the eight that exist. Checking it turned up a second, older error in the same passage: wiki-query was given as six steps when it has seven, wrong independently of this package and never noticed, because nothing verifies the number. Both corrected in 7.0.0-beta.10, commit 3c1d4cb, along with three more stale enumerations found in the same sweep (instructions/bootstrap.md's skill list, the Scope sections of stack-dev/stack-close, and test_the_real_repo_publishes_the_six_wiki_skills → ..._every_skill). The rule itself did not move: the threshold is still "one flow of eight steps or more and steps whose omission is silent", and no skill changed sides - gtd-weekly-review (five), stack-dev (six) and stack-close (four) all sit below it.
The structural question that sweep exposed - that the passage quotes step counts of other files, which go stale with nothing checking them - is #130, deliberately not answered here.
tools/wikitool instructions verify: OK (23 instructions, 8 skills valid, 16 published copies match source).
pytest in tools/: 1383 passed, on both commits.
No docs/ page needed a pull-through in either pass: none of the six pages reached from AGENTS.md names the skill, the naming convention, or the checklist threshold, so none went stale.
Single model throughout - no model switch offered or taken. One session ran the design/decision phase, the mechanical middle (rename, description rewrites, CONTRACT.md edits, TOC regen, verify/pytest, both version bumps), and both closing phases.
The published skill collection had grown three naming shapes where it should have had three *families*. `wiki-ingest`/`wiki-lint`/`wiki-manage`/`wiki-query`/`wiki-status` and `stack-dev`/`stack-close` each named their domain; `weekly-review` named neither, and sat outside both.
Separately, all eight `description:` fields were written in the imperative ("Process a new source file…"), while Anthropic's skill-authoring guidance asks for third person, because the description is injected into the system prompt and an inconsistent point of view degrades skill selection.
Neither convention was written down anywhere, which is why the drift happened in the first place. Both are now fixed and documented.
## Decisions (as implemented)
**D1 - The new name is `gtd-weekly-review`, not `wiki-review`.** Done.
GTD is a named, first-class layer in this stack, not a methodology label: the `kb/gtd/` collection, the `project` type ("a committed initiative (a GTD project)"), `wikitool review` ("The GTD weekly review", `tools/CONTRACT.md`), the `chemenu.tasks` provider layer, `.wikitool-tasks.json`, and `docs/knowledge-and-commitment.md`. A `wiki-` prefix would have flattened that boundary.
**D2 - The prefix names the subject domain, the directory names the distribution boundary.** Done, and now written down.
Three families: `wiki-` (knowledge pipeline, under `instructions/`), `gtd-` (commitment layer, under `instructions/`), `stack-` (the stack itself, under `instructions/dev/`). `instructions/CONTRACT.md` § "Writing an instruction" gained a new subsection, "A skill's name declares its family", stating this - with the `stack-dev`/`stack-close` names themselves kept inside a `<!-- dist:strip-start/end -->` block, since `CONTRACT.md` ships to distributed instances and those two names would otherwise dangle past `dist export`.
**D3 - No sibling `gtd-` skills created on spec.** Held. Only `gtd-weekly-review` exists in the new family.
**D4 - Version part: `--patch`, no `--breaking`.** Done as planned.
`weekly-review` was introduced by this same running candidate (never released), so no instance in the wild carried the old name - nothing to break. `tools/wikitool version bump --patch` on the `7.0.0` candidate produced `7.0.0-beta.8` → `7.0.0-beta.9`; the bump still shows as boundary-crossing because the candidate already crossed earlier in the same run (`project`/`kb/gtd/` adoption requirement) - the running candidate's compatibility state is max-wins and does not step back down for a later, non-crossing bump.
**D5 - The historical `7.0.0-beta.8` bump-list title stayed as written.** Done - it is machine-managed, dated evidence of what that bump actually did.
**Third-person descriptions**, decided during implementation, not originally scoped as its own decision: all eight skills' `description:` fields were rewritten from imperative to third person ("Processes...", "Answers...", "Switches...", etc.), matching Anthropic's guidance verbatim example ("Processes Excel files and generates reports"). `instructions/CONTRACT.md` gained a second new subsection, "A skill's `description` speaks in third person", noting this binds only `instructions/<name>/SKILL.md` - the flat `instructions/<name>.md` form keeps its existing imperative-title convention, since that `description` is read on demand rather than injected into the system prompt.
## Acceptance criteria
- [x] `instructions/gtd-weekly-review/SKILL.md` exists; `instructions/weekly-review/` does not. `name: gtd-weekly-review`, H1 `# GTD Weekly Review`.
- [x] `tools/wikitool instructions list` names `gtd-weekly-review`, no `weekly-review`. `instructions sync` pruned both stale `.agents/skills/weekly-review/` and `.claude/skills/weekly-review/` (reported "removed 2 stale").
- [x] No file outside `CHANGES.md` and `commonplace/` contains `weekly-review` as a skill name - swept after every edit; the only survivors are the dated `CHANGES.md` entries (7.0.0-beta.8's bump title/changeset, left per D5) and `commonplace/kb/sources/koylanai-personal-brain-os.{md,json}`, vendored third-party text about an unrelated `npm run weekly-review` script.
- [x] All eight published skills' `description:` are third person, still state what+when, all comfortably under 1024 characters.
- [x] `instructions/CONTRACT.md` § "Writing an instruction" carries both conventions, each once: "A skill's name declares its family" and "A skill's `description` speaks in third person" - both note nothing checks them mechanically.
- [x] Pulled through: `AGENTS.md` § Routing skill table, `README.md` (skill table row + the `gtd-weekly-review` mention in prose), `INSTALL.md`, `instructions/setup-instance.md`.
- [x] `test_weekly_review_skill_names_no_provider` → renamed `test_gtd_weekly_review_skill_names_no_provider`, reads `instructions/gtd-weekly-review/SKILL.md`, passes.
- [x] `tools/wikitool docs verify`, `tools/wikitool instructions verify`, and the full `pytest` suite (1383 tests) all pass. `docs verify` initially caught a real defect introduced during this work: the new "declares its family" prose named `stack-dev`/`stack-close` outside `instructions/dev/` and outside a `dist:strip` block, which would have dangled in a distributed instance - fixed by wrapping those two names in `<!-- dist:strip-start/end -->`, matching the existing convention already used for the same names in `AGENTS.md` and `README.md`.
- [x] `tools/wikitool version bump --patch` made (`7.0.0-beta.9`), changeset prose written under `### Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions` in `CHANGES.md`.
Published as commit `52ba5ba` (`tools/wikitool publish`, cleared through the Mass-Update Gate at 17 files - the user approved the full file-and-line breakdown before `--confirm`).
## Follow-up: the out-of-scope note was checked after all
The note below originally read "not moved here; worth its own issue if it's ever judged wrong". It was judged, immediately after closing, and it *was* wrong - so it was fixed in a second commit rather than left standing.
`instructions/CONTRACT.md` § "When a skill carries a copy-in checklist" counted "the two skills that have such a block and the three that do not" - five of the eight that exist. Checking it turned up a second, older error in the same passage: `wiki-query` was given as six steps when it has seven, wrong independently of this package and never noticed, because nothing verifies the number. Both corrected in `7.0.0-beta.10`, commit `3c1d4cb`, along with three more stale enumerations found in the same sweep (`instructions/bootstrap.md`'s skill list, the Scope sections of `stack-dev`/`stack-close`, and `test_the_real_repo_publishes_the_six_wiki_skills` → `..._every_skill`). The rule itself did not move: the threshold is still "one flow of eight steps or more *and* steps whose omission is silent", and no skill changed sides - `gtd-weekly-review` (five), `stack-dev` (six) and `stack-close` (four) all sit below it.
The structural question that sweep exposed - that the passage quotes step counts of *other* files, which go stale with nothing checking them - is **#130**, deliberately not answered here.
## Verification / model
- `tools/wikitool docs verify`: OK (57 commands, 9 type-specs, TOCs current, `CHANGES.md` documents `7.0.0-beta.10`).
- `tools/wikitool instructions verify`: OK (23 instructions, 8 skills valid, 16 published copies match source).
- `pytest` in `tools/`: 1383 passed, on both commits.
- No `docs/` page needed a pull-through in either pass: none of the six pages reached from `AGENTS.md` names the skill, the naming convention, or the checklist threshold, so none went stale.
- Single model throughout - no model switch offered or taken. One session ran the design/decision phase, the mechanical middle (rename, description rewrites, CONTRACT.md edits, TOC regen, verify/pytest, both version bumps), and both closing phases.
Changelog: Nachtrag nach dem Schließen - der als "out of scope" vermerkte Zähler wurde doch noch geprüft und korrigiert (7.0.0-beta.10, Commit 3c1d4cb). Der Abschnitt "Out of scope, confirmed left alone" im Body ist damit überholt und unten berichtigt; die strukturelle Restfrage steht als #130.
Beim Nachprüfen kam ein zweiter, älterer Fehler in derselben Passage heraus: wiki-query war mit sechs Schritten angegeben, hat aber sieben - unabhängig von diesem Paket entstanden und nie bemerkt, weil nichts die Zahl prüft.
**Changelog:** Nachtrag nach dem Schließen - der als "out of scope" vermerkte Zähler wurde doch noch geprüft und korrigiert (`7.0.0-beta.10`, Commit `3c1d4cb`). Der Abschnitt "Out of scope, confirmed left alone" im Body ist damit überholt und unten berichtigt; die strukturelle Restfrage steht als #130.
Beim Nachprüfen kam ein zweiter, älterer Fehler in derselben Passage heraus: `wiki-query` war mit sechs Schritten angegeben, hat aber sieben - unabhängig von diesem Paket entstanden und nie bemerkt, weil nichts die Zahl prüft.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
The published skill collection had grown three naming shapes where it should have had three families.
wiki-ingest/wiki-lint/wiki-manage/wiki-query/wiki-statusandstack-dev/stack-closeeach named their domain;weekly-reviewnamed neither, and sat outside both.Separately, all eight
description:fields were written in the imperative ("Process a new source file…"), while Anthropic's skill-authoring guidance asks for third person, because the description is injected into the system prompt and an inconsistent point of view degrades skill selection.Neither convention was written down anywhere, which is why the drift happened in the first place. Both are now fixed and documented.
Decisions (as implemented)
D1 - The new name is
gtd-weekly-review, notwiki-review. Done.GTD is a named, first-class layer in this stack, not a methodology label: the
kb/gtd/collection, theprojecttype ("a committed initiative (a GTD project)"),wikitool review("The GTD weekly review",tools/CONTRACT.md), thechemenu.tasksprovider layer,.wikitool-tasks.json, anddocs/knowledge-and-commitment.md. Awiki-prefix would have flattened that boundary.D2 - The prefix names the subject domain, the directory names the distribution boundary. Done, and now written down.
Three families:
wiki-(knowledge pipeline, underinstructions/),gtd-(commitment layer, underinstructions/),stack-(the stack itself, underinstructions/dev/).instructions/CONTRACT.md§ "Writing an instruction" gained a new subsection, "A skill's name declares its family", stating this - with thestack-dev/stack-closenames themselves kept inside a<!-- dist:strip-start/end -->block, sinceCONTRACT.mdships to distributed instances and those two names would otherwise dangle pastdist export.D3 - No sibling
gtd-skills created on spec. Held. Onlygtd-weekly-reviewexists in the new family.D4 - Version part:
--patch, no--breaking. Done as planned.weekly-reviewwas introduced by this same running candidate (never released), so no instance in the wild carried the old name - nothing to break.tools/wikitool version bump --patchon the7.0.0candidate produced7.0.0-beta.8→7.0.0-beta.9; the bump still shows as boundary-crossing because the candidate already crossed earlier in the same run (project/kb/gtd/adoption requirement) - the running candidate's compatibility state is max-wins and does not step back down for a later, non-crossing bump.D5 - The historical
7.0.0-beta.8bump-list title stayed as written. Done - it is machine-managed, dated evidence of what that bump actually did.Third-person descriptions, decided during implementation, not originally scoped as its own decision: all eight skills'
description:fields were rewritten from imperative to third person ("Processes...", "Answers...", "Switches...", etc.), matching Anthropic's guidance verbatim example ("Processes Excel files and generates reports").instructions/CONTRACT.mdgained a second new subsection, "A skill'sdescriptionspeaks in third person", noting this binds onlyinstructions/<name>/SKILL.md- the flatinstructions/<name>.mdform keeps its existing imperative-title convention, since thatdescriptionis read on demand rather than injected into the system prompt.Acceptance criteria
instructions/gtd-weekly-review/SKILL.mdexists;instructions/weekly-review/does not.name: gtd-weekly-review, H1# GTD Weekly Review.tools/wikitool instructions listnamesgtd-weekly-review, noweekly-review.instructions syncpruned both stale.agents/skills/weekly-review/and.claude/skills/weekly-review/(reported "removed 2 stale").CHANGES.mdandcommonplace/containsweekly-reviewas a skill name - swept after every edit; the only survivors are the datedCHANGES.mdentries (7.0.0-beta.8's bump title/changeset, left per D5) andcommonplace/kb/sources/koylanai-personal-brain-os.{md,json}, vendored third-party text about an unrelatednpm run weekly-reviewscript.description:are third person, still state what+when, all comfortably under 1024 characters.instructions/CONTRACT.md§ "Writing an instruction" carries both conventions, each once: "A skill's name declares its family" and "A skill'sdescriptionspeaks in third person" - both note nothing checks them mechanically.AGENTS.md§ Routing skill table,README.md(skill table row + thegtd-weekly-reviewmention in prose),INSTALL.md,instructions/setup-instance.md.test_weekly_review_skill_names_no_provider→ renamedtest_gtd_weekly_review_skill_names_no_provider, readsinstructions/gtd-weekly-review/SKILL.md, passes.tools/wikitool docs verify,tools/wikitool instructions verify, and the fullpytestsuite (1383 tests) all pass.docs verifyinitially caught a real defect introduced during this work: the new "declares its family" prose namedstack-dev/stack-closeoutsideinstructions/dev/and outside adist:stripblock, which would have dangled in a distributed instance - fixed by wrapping those two names in<!-- dist:strip-start/end -->, matching the existing convention already used for the same names inAGENTS.mdandREADME.md.tools/wikitool version bump --patchmade (7.0.0-beta.9), changeset prose written under### Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen DescriptionsinCHANGES.md.Published as commit
52ba5ba(tools/wikitool publish, cleared through the Mass-Update Gate at 17 files - the user approved the full file-and-line breakdown before--confirm).Follow-up: the out-of-scope note was checked after all
The note below originally read "not moved here; worth its own issue if it's ever judged wrong". It was judged, immediately after closing, and it was wrong - so it was fixed in a second commit rather than left standing.
instructions/CONTRACT.md§ "When a skill carries a copy-in checklist" counted "the two skills that have such a block and the three that do not" - five of the eight that exist. Checking it turned up a second, older error in the same passage:wiki-querywas given as six steps when it has seven, wrong independently of this package and never noticed, because nothing verifies the number. Both corrected in7.0.0-beta.10, commit3c1d4cb, along with three more stale enumerations found in the same sweep (instructions/bootstrap.md's skill list, the Scope sections ofstack-dev/stack-close, andtest_the_real_repo_publishes_the_six_wiki_skills→..._every_skill). The rule itself did not move: the threshold is still "one flow of eight steps or more and steps whose omission is silent", and no skill changed sides -gtd-weekly-review(five),stack-dev(six) andstack-close(four) all sit below it.The structural question that sweep exposed - that the passage quotes step counts of other files, which go stale with nothing checking them - is #130, deliberately not answered here.
Verification / model
tools/wikitool docs verify: OK (57 commands, 9 type-specs, TOCs current,CHANGES.mddocuments7.0.0-beta.10).tools/wikitool instructions verify: OK (23 instructions, 8 skills valid, 16 published copies match source).pytestintools/: 1383 passed, on both commits.docs/page needed a pull-through in either pass: none of the six pages reached fromAGENTS.mdnames the skill, the naming convention, or the checklist threshold, so none went stale.torben referenced this issue2026-09-20 09:52:45 +00:00
Changelog: Nachtrag nach dem Schließen - der als "out of scope" vermerkte Zähler wurde doch noch geprüft und korrigiert (
7.0.0-beta.10, Commit3c1d4cb). Der Abschnitt "Out of scope, confirmed left alone" im Body ist damit überholt und unten berichtigt; die strukturelle Restfrage steht als #130.Beim Nachprüfen kam ein zweiter, älterer Fehler in derselben Passage heraus:
wiki-querywar mit sechs Schritten angegeben, hat aber sieben - unabhängig von diesem Paket entstanden und nie bemerkt, weil nichts die Zahl prüft.torben referenced this issue2026-10-03 20:31:09 +00:00