From 52ba5ba768f292830f5e10b5df606260660f4dbf Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Sun, 20 Sep 2026 11:44:21 +0200 Subject: [PATCH] Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions (#129) Files changed: - AGENTS.md - CHANGES.md - INSTALL.md - README.md - VERSION - instructions/CONTRACT.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/gtd-weekly-review/SKILL.md - instructions/setup-instance.md - instructions/weekly-review/SKILL.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 - tools/chemenu/tests/test_instructions_cmd.py --- AGENTS.md | 2 +- CHANGES.md | 19 ++++++++++- INSTALL.md | 2 +- README.md | 4 +-- VERSION | 2 +- instructions/CONTRACT.md | 34 +++++++++++++++++++ instructions/dev/stack-close/SKILL.md | 2 +- instructions/dev/stack-dev/SKILL.md | 2 +- .../SKILL.md | 6 ++-- instructions/setup-instance.md | 2 +- instructions/wiki-ingest/SKILL.md | 2 +- instructions/wiki-lint/SKILL.md | 2 +- instructions/wiki-manage/SKILL.md | 2 +- instructions/wiki-query/SKILL.md | 2 +- instructions/wiki-status/SKILL.md | 2 +- tools/chemenu/tests/test_instructions_cmd.py | 6 ++-- 16 files changed, 71 insertions(+), 20 deletions(-) rename instructions/{weekly-review => gtd-weekly-review}/SKILL.md (95%) diff --git a/AGENTS.md b/AGENTS.md index fba53d5..0d827dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -237,7 +237,7 @@ ships the first verbatim and the second only as a `.template`. | `wiki-manage` | A page needs creating, or new information needs integrating into one | | `wiki-lint` | The wiki needs a health check (also every 10 sources) | | `wiki-status` | A quick read-only snapshot is wanted, without a full lint | -| `weekly-review` | `wikitool review` has findings nobody has acted on yet, or the user asks for the weekly review | +| `gtd-weekly-review` | `wikitool review` has findings nobody has acted on yet, or the user asks for the weekly review | Shared procedures that several skills call into: `tools/wikitool instructions list`. diff --git a/CHANGES.md b/CHANGES.md index 65f7320..a037ce8 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse. --- -## 7.0.0-beta.8 - 2026-09-20 - docs/-Nachzug: Exit 42 als Haltung, und die Adoption eines neu ausgelieferten Templates +## 7.0.0-beta.9 - 2026-09-20 - Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions **Author:** Torben Nehmer @@ -79,6 +79,7 @@ concern - readable here, never shipped as something to parse. **Low impact** - new project: Testabdeckung fuer die required-responsibility-Ablehnung - docs/-Nachzug: Exit 42 als Haltung, und die Adoption eines neu ausgelieferten Templates +- Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions ### Typ `project` und Collection `kb/gtd/`: das Vorhaben als eigene Seitenart @@ -290,6 +291,22 @@ beide unpruefbar, weil eine `docs/`-Seite per Konstruktion keinen normativen Sat eine Gestalt, in der „das Upgrade schreibt diese Datei nie" zu Arbeit wird, mit Verweis auf den Schritt in `upgrade-instance.md`, den Stack 7.0.0-beta.7 dort angelegt hat. +### Skill-Namensfamilien: weekly-review -> gtd-weekly-review, dritte Person in allen Descriptions + +Gitea #129: the published skill collection had drifted into three naming shapes where it should +have three *families*. `weekly-review` (added earlier in this same candidate, never released) +named neither its domain nor its distribution boundary, unlike `wiki-*` and `stack-*` either +side of it - renamed to `gtd-weekly-review`, joining a new `gtd-` prefix for the commitment layer +(`kb/gtd/`, `types/project.md`, `docs/knowledge-and-commitment.md`) that sits beside `wiki-` (the +knowledge pipeline) and `stack-` (the stack's own development, under `instructions/dev/`). +`instructions/CONTRACT.md` § "Writing an instruction" now states both the family-prefix +convention and, separately, that a skill's `description` speaks in third person per Anthropic's +skill-authoring guidance - all eight published skills' descriptions were rewritten to match +("Processes...", not "Process..."); the flat `instructions/.md` form keeps its existing +imperative-title convention, since its `description` is read on demand rather than injected into +the system prompt. No `--breaking` line: the renamed skill was introduced by this same +unreleased candidate, so no existing instance carries the old name to migrate away from. + --- ## 6.2.0 - 2026-09-19 - Entity-Subtyp project nach codebase umbenannt diff --git a/INSTALL.md b/INSTALL.md index 4dae51d..5b4bac4 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -292,7 +292,7 @@ tools/wikitool version check ``` **Aufgaben-Tracker anbinden - optional.** Der Wochenrückblick (`tools/wikitool review`, Skill -`weekly-review`) gleicht die Projektseiten unter `kb/gtd/` gegen einen Aufgaben-Tracker ab. Welcher +`gtd-weekly-review`) gleicht die Projektseiten unter `kb/gtd/` gegen einen Aufgaben-Tracker ab. Welcher das ist, steht in `.wikitool-tasks.json` im Repo-Root - der dritten Datei dieser Art neben `.wikitool-telemetry.json` und `.wikitool-remotes.json`: pro Checkout, ohne `.template`, und **gitignored, sobald ein Token darin liegt**. Fehlt sie, ist schlicht kein Tracker konfiguriert; diff --git a/README.md b/README.md index bd11f37..fa2ea87 100644 --- a/README.md +++ b/README.md @@ -239,7 +239,7 @@ Nothing syncs between the two. `tools/wikitool review` joins them at read time over the project name and prints what needs a decision: initiatives with no next action, waiting-fors past their follow-up date, tracker projects with no page, active pages with no open loop, someday items gone stale. It stores nothing - -not even a report file. The `weekly-review` skill then walks the findings with +not even a report file. The `gtd-weekly-review` skill then walks the findings with you and turns each one into a decision; `tools/wikitool new project` is what gives a new initiative its page and its tracker project under one name. @@ -280,7 +280,7 @@ themselves live as independently-discoverable skills under `.agents/skills/` | `wiki-lint` | Health-check the wiki: structural scan, raw coverage, semantic review | | `wiki-manage` | Create a new entity/concept/source/comparison page, or update an existing page with new information | | `wiki-status` | Read-only snapshot: page counts, orphans, uncovered raw files, most-connected pages | -| `weekly-review` | Turn `wikitool review`'s findings into decisions and page updates - the GTD weekly review | +| `gtd-weekly-review` | Turns `wikitool review`'s findings into decisions and page updates - the GTD weekly review | Each skill's underlying mechanical work (frontmatter, cross-references, index/log, decay math, publishing) is delegated to `tools/wikitool` - never hand-edited. diff --git a/VERSION b/VERSION index e5533f6..17e1a97 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -7.0.0-beta.8 +7.0.0-beta.9 diff --git a/instructions/CONTRACT.md b/instructions/CONTRACT.md index ed85b5e..06f5d08 100644 --- a/instructions/CONTRACT.md +++ b/instructions/CONTRACT.md @@ -18,6 +18,8 @@ alongside [AGENTS.md](../AGENTS.md). - [Publishing](#publishing) - [Writing an instruction](#writing-an-instruction) - [A skill's H1 is a name, not an imperative](#a-skills-h1-is-a-name-not-an-imperative) + - [A skill's `description` speaks in third person](#a-skills-description-speaks-in-third-person) + - [A skill's name declares its family](#a-skills-name-declares-its-family) - [A skill's outbound reference is a plain path, not a link](#a-skills-outbound-reference-is-a-plain-path-not-a-link) - [Reference depth: bundled files, not repo-wide contracts](#reference-depth-bundled-files-not-repo-wide-contracts) - [When a skill carries a copy-in checklist](#when-a-skill-carries-a-copy-in-checklist) @@ -202,6 +204,38 @@ exception in the same breath - "for promoted skills, the skill name is the title That is the whole exception. Everything else in this section binds a `SKILL.md` exactly as it binds an instruction. +### A skill's `description` speaks in third person + +Anthropic's skill-authoring guidance requires third person in a skill's `description`, because it +is injected into the system prompt for skill selection and an inconsistent point of view degrades +that selection - "Processes Excel files and generates reports", never "I can help you process..." +or "Process...". This binds every `instructions//SKILL.md` in this repo. The flat +`instructions/.md` form's `description` (above) is read on demand rather than injected as +system-prompt metadata, so it keeps the imperative/label freedom that form already allows. + +Nothing checks this mechanically - `tools/wikitool docs verify`/`instructions verify` validate a +`description`'s presence and length, not its grammatical voice - so it holds only as long as each +new skill is written to match the ones around it. + +### A skill's name declares its family + +Three prefixes exist today, each naming the subject domain a skill operates on, not the +distribution boundary it ships behind: `wiki-` for the knowledge pipeline (`wiki-ingest`, +`wiki-lint`, `wiki-manage`, `wiki-query`, `wiki-status`), `gtd-` for the commitment layer +(`gtd-weekly-review` - see `kb/gtd/COLLECTION.md` and `docs/knowledge-and-commitment.md` for why +that layer is named GTD rather than folded into `wiki-`), and `stack-` for the stack's own +development, nested under `instructions/dev/` and therefore never present in a distributed +instance (`instructions/dev/` above). + +Dev-instance-only: the two skills in that family today are `stack-dev` and `stack-close`. + +A new skill takes the prefix of the family it belongs to, or opens a new one deliberately - never +a bare name. + +This is a convention, not something the tool enforces: an unprefixed or fourth-family name would +compile, publish and pass every check exactly like the three above, so it is written down here for +the next session to read before adding one. + ### A skill's outbound reference is a plain path, not a link `tools/wikitool instructions sync` copies each `SKILL.md` byte for byte into diff --git a/instructions/dev/stack-close/SKILL.md b/instructions/dev/stack-close/SKILL.md index 534529e..4d38f57 100644 --- a/instructions/dev/stack-close/SKILL.md +++ b/instructions/dev/stack-close/SKILL.md @@ -1,6 +1,6 @@ --- name: stack-close -description: Close out a stack-dev work package after its publish has landed - rewrite the issue body to its final state, check for docs/ staleness, and name which model ran which phase of the session. Use right after a stack-dev session's tools/wikitool publish succeeds, or when resuming a package that was published but never closed. +description: Closes out a stack-dev work package after its publish has landed - rewrites the issue body to its final state, checks for docs/ staleness, and names which model ran which phase of the session. Use right after a stack-dev session's tools/wikitool publish succeeds, or when resuming a package that was published but never closed. --- # Stack Close diff --git a/instructions/dev/stack-dev/SKILL.md b/instructions/dev/stack-dev/SKILL.md index 7d5df29..97c9d7f 100644 --- a/instructions/dev/stack-dev/SKILL.md +++ b/instructions/dev/stack-dev/SKILL.md @@ -1,6 +1,6 @@ --- name: stack-dev -description: Switch a session into tool-development mode - extending tools/wikitool, the compiler, the type schema, or the instruction/skill layer itself, instead of operating on wiki content. Use when the user asks to add a wikitool command, change a type-spec, fix or extend the compiler, or otherwise work on the stack rather than ingest/query/manage/lint the wiki. +description: Switches a session into tool-development mode - extending tools/wikitool, the compiler, the type schema, or the instruction/skill layer itself, instead of operating on wiki content. Use when the user asks to add a wikitool command, change a type-spec, fix or extend the compiler, or otherwise work on the stack rather than ingest/query/manage/lint the wiki. --- # Stack Development Mode diff --git a/instructions/weekly-review/SKILL.md b/instructions/gtd-weekly-review/SKILL.md similarity index 95% rename from instructions/weekly-review/SKILL.md rename to instructions/gtd-weekly-review/SKILL.md index be69645..b1b201d 100644 --- a/instructions/weekly-review/SKILL.md +++ b/instructions/gtd-weekly-review/SKILL.md @@ -1,9 +1,9 @@ --- -name: weekly-review -description: Turn the findings from `wikitool review` into decisions and page updates - the GTD Weekly Review, with a machine that prepares the list instead of a human reconstructing it from memory. Use when the user asks for "the weekly review", "review my projects", "what's stalled", or after `wikitool review` has findings nobody has acted on yet. +name: gtd-weekly-review +description: Turns the findings from `wikitool review` into decisions and page updates - the GTD Weekly Review, with a machine that prepares the list instead of a human reconstructing it from memory. Use when the user asks for "the weekly review", "review my projects", "what's stalled", or after `wikitool review` has findings nobody has acted on yet. --- -# Weekly Review +# GTD Weekly Review **Purpose:** A finding from `wikitool review` is not an action by itself - "this initiative looks stalled" can mean a next action is missing, the initiative was deliberately paused, or it is diff --git a/instructions/setup-instance.md b/instructions/setup-instance.md index 1fc00f5..37283ac 100644 --- a/instructions/setup-instance.md +++ b/instructions/setup-instance.md @@ -303,7 +303,7 @@ and ready for its first ingest. 16. **Restart the agent session.** Harnesses read the skill directories at startup; only afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint`, `wiki-status` and - `weekly-review` available. + `gtd-weekly-review` available. ## Scope diff --git a/instructions/wiki-ingest/SKILL.md b/instructions/wiki-ingest/SKILL.md index 0e68186..5092dfa 100644 --- a/instructions/wiki-ingest/SKILL.md +++ b/instructions/wiki-ingest/SKILL.md @@ -1,6 +1,6 @@ --- name: wiki-ingest -description: Process a new source file into the LLM wiki - extract entities and concepts, create a source summary page, cross-reference, rebuild indexes, and publish. Use when the user drops a file into incoming/ or raw/, or says "ingest ", "process this source", "add this to the wiki". +description: Processes a new source file into the LLM wiki - extracts entities and concepts, creates a source summary page, cross-references, rebuilds indexes, and publishes. Use when the user drops a file into incoming/ or raw/, or says "ingest ", "process this source", "add this to the wiki". --- # Wiki Ingest diff --git a/instructions/wiki-lint/SKILL.md b/instructions/wiki-lint/SKILL.md index eb9cfb9..2fc47e0 100644 --- a/instructions/wiki-lint/SKILL.md +++ b/instructions/wiki-lint/SKILL.md @@ -1,6 +1,6 @@ --- name: wiki-lint -description: Health-check the LLM wiki - broken links, orphan pages, uncovered raw files, stale claims, duplicated rules, missing cross-references. Use when the user says "lint the wiki", "health-check the wiki", or periodically every 10 sources per the Maintenance Schedule. +description: Checks the health of the LLM wiki - broken links, orphan pages, uncovered raw files, stale claims, duplicated rules, missing cross-references. Use when the user says "lint the wiki", "health-check the wiki", or periodically every 10 sources per the Maintenance Schedule. --- # Wiki Lint diff --git a/instructions/wiki-manage/SKILL.md b/instructions/wiki-manage/SKILL.md index e910059..f0e2d93 100644 --- a/instructions/wiki-manage/SKILL.md +++ b/instructions/wiki-manage/SKILL.md @@ -1,6 +1,6 @@ --- name: wiki-manage -description: Create a new wiki page (entity, concept, source, comparison) or update an existing page with new information, including cross-references, index/log, and publish. Use when the user says "create a new entity/concept/comparison", "add a page for X", "update the X page", or new information needs integrating into an existing page. +description: Creates a new wiki page (entity, concept, source, comparison) or updates an existing page with new information, including cross-references, index/log, and publishing. Use when the user says "create a new entity/concept/comparison", "add a page for X", "update the X page", or new information needs integrating into an existing page. --- # Wiki Manage diff --git a/instructions/wiki-query/SKILL.md b/instructions/wiki-query/SKILL.md index 73087c1..d5dda6f 100644 --- a/instructions/wiki-query/SKILL.md +++ b/instructions/wiki-query/SKILL.md @@ -1,6 +1,6 @@ --- name: wiki-query -description: Answer a question using the LLM wiki's compiled knowledge - read-only, cites sources, can file a valuable answer back as a new page. Use when the user asks a question about entities, projects, concepts, or anything the wiki might know, or says "query the wiki", "what do we know about X", "search the wiki". +description: Answers a question using the LLM wiki's compiled knowledge - read-only, cites sources, can file a valuable answer back as a new page. Use when the user asks a question about entities, projects, concepts, or anything the wiki might know, or says "query the wiki", "what do we know about X", "search the wiki". --- # Wiki Query diff --git a/instructions/wiki-status/SKILL.md b/instructions/wiki-status/SKILL.md index b16e321..f429fd6 100644 --- a/instructions/wiki-status/SKILL.md +++ b/instructions/wiki-status/SKILL.md @@ -1,6 +1,6 @@ --- name: wiki-status -description: Show a quick read-only snapshot of the LLM wiki - page counts, orphan pages, uncovered raw files, recent activity. Use when the user says "wiki status", "show wiki statistics", "what's new", or wants a quick health snapshot without running a full lint. +description: Shows a quick read-only snapshot of the LLM wiki - page counts, orphan pages, uncovered raw files, recent activity. Use when the user says "wiki status", "show wiki statistics", "what's new", or wants a quick health snapshot without running a full lint. --- # Wiki Status diff --git a/tools/chemenu/tests/test_instructions_cmd.py b/tools/chemenu/tests/test_instructions_cmd.py index 6c662dc..d9e2652 100644 --- a/tools/chemenu/tests/test_instructions_cmd.py +++ b/tools/chemenu/tests/test_instructions_cmd.py @@ -75,13 +75,13 @@ def test_the_real_repo_publishes_the_six_wiki_skills(): } <= names -def test_weekly_review_skill_names_no_provider(): +def test_gtd_weekly_review_skill_names_no_provider(): """#119 D25/#127 AC1: the skill is the one document meant to read identically in every instance, whichever task-tracker provider it runs against - so its body must name none of them, and none of a provider's file or API shape either. Reads the real repo's file, not a fixture, because the claim is about what ships, not about the discovery logic.""" - text = (config.INSTRUCTIONS_DIR / "weekly-review" / "SKILL.md").read_text(encoding="utf-8").lower() + text = (config.INSTRUCTIONS_DIR / "gtd-weekly-review" / "SKILL.md").read_text(encoding="utf-8").lower() forbidden = [ "super productivity", "azure devops", @@ -91,7 +91,7 @@ def test_weekly_review_skill_names_no_provider(): ".wikitool-tasks.json", ] hits = [term for term in forbidden if term in text] - assert not hits, f"weekly-review/SKILL.md names a provider or its shape: {hits}" + assert not hits, f"gtd-weekly-review/SKILL.md names a provider or its shape: {hits}" def test_instructions_dev_flat_file_is_discovered(layer):