From 44909c9e4704485306f1557d89960ebf13186595 Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Sun, 20 Sep 2026 07:51:43 +0200 Subject: [PATCH] Skill weekly-review: wikitool review's findings become decisions (#119) Files changed: - AGENTS.md - CHANGES.md - README.md - VERSION - instructions/weekly-review/SKILL.md - tools/chemenu/tests/test_instructions_cmd.py --- AGENTS.md | 1 + CHANGES.md | 18 +++- README.md | 1 + VERSION | 2 +- instructions/weekly-review/SKILL.md | 105 +++++++++++++++++++ tools/chemenu/tests/test_instructions_cmd.py | 19 ++++ 6 files changed, 144 insertions(+), 2 deletions(-) create mode 100644 instructions/weekly-review/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index 1fbc433..3cfb2c7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -235,6 +235,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 | Shared procedures that several skills call into: `tools/wikitool instructions list`. diff --git a/CHANGES.md b/CHANGES.md index 3f90e93..7b2988e 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse. --- -## 7.0.0-beta.5 - 2026-09-20 - new project: Testabdeckung fuer die required-responsibility-Ablehnung +## 7.0.0-beta.6 - 2026-09-20 - Skill weekly-review: turning wikitool review's findings into decisions **Author:** Torben Nehmer @@ -73,6 +73,7 @@ concern - readable here, never shipped as something to parse. - Task-tracker provider layer, with a Super Productivity adapter - wikitool review: the weekly GTD review as a read-time join - wikitool new project: Seite und Tracker-Projekt unter einem Namen +- Skill weekly-review: turning wikitool review's findings into decisions **Low impact** - new project: Testabdeckung fuer die required-responsibility-Ablehnung @@ -206,6 +207,21 @@ Enums wird abgelehnt - beides galt schon vorher generisch ueber `types/project.s der das fuer den fehlenden Fall (`--set responsibility=...` ganz weggelassen) tatsaechlich belegt, statt es nur zu behaupten. +### Skill weekly-review: turning wikitool review's findings into decisions + +Gitea #119 (Paket #127): `instructions/weekly-review/SKILL.md`, publiziert nach `.agents/skills/` +und `.claude/skills/`. `wikitool review` liefert fuenf Befunde (#125); dieser Skill fuehrt das +Gespraech, das aus jedem eine Entscheidung macht - je Befund mindestens zwei Handlungsoptionen und +ein Unterscheidungsmerkmal, wie in #127s Akzeptanzkriterien gefordert. + +Der Skill nennt bewusst keinen Provider, keine Datei- und keine API-Form (D25) - eine neue +Regressionstest (`test_weekly_review_skill_names_no_provider`) haelt das am echten Repo-Inhalt +fest, nicht nur als Review-Behauptung. Erinnert im Text an D28 (Personen in `## Beteiligte` +bleiben Erwaehnung, bekommen keine Seite) und D7 (die Seite fasst die Aufgabenliste nie +zusammen). Die Kommandoflaeche bleibt bei `review`/`new project`; alles Aufgabenbezogene - eine +naechste Aktion anlegen, `follow_up_at` verschieben, einen Someday-Eintrag streichen - bleibt eine +Handlung im Tracker selbst, weil dafuer kein `wikitool`-Kommando existiert (D31). + --- ## 6.2.0 - 2026-09-19 - Entity-Subtyp project nach codebase umbenannt diff --git a/README.md b/README.md index cbd41a8..462be0f 100644 --- a/README.md +++ b/README.md @@ -257,6 +257,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 | 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 28af6d3..53183fc 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -7.0.0-beta.5 +7.0.0-beta.6 diff --git a/instructions/weekly-review/SKILL.md b/instructions/weekly-review/SKILL.md new file mode 100644 index 0000000..be69645 --- /dev/null +++ b/instructions/weekly-review/SKILL.md @@ -0,0 +1,105 @@ +--- +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. +--- + +# 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 +actually finished. Which one is true is a human judgment. This skill runs the conversation that +collects that judgment and carries it out. + +**Trigger:** The user asks for a weekly review, or `wikitool review` has findings nobody has +looked at yet. + +**Before the first `wikitool` call:** `instructions/session-setup.md`. + +**Provider-neutral by design.** Nothing below names a task-tracker provider, a file format or an +API - only the tracker's generic role. That is deliberate: this skill is the one document that +must read identically in every instance, whichever tracker it runs against. Anything the tracker +itself must do - add a task, reschedule a reminder, remove an item - is described as an action the +user takes in their tracker, because `wikitool` has no command for it: the only two GTD commands +that exist are `review` (read-only) and `new project` (page + tracker project creation). That +narrow command surface is deliberate (see the reasoning in `types/project.md` and +`kb/gtd/COLLECTION.md`, which this skill does not repeat) - do not reach for a tracker-specific +tool or API to "just do it faster". + +## Steps + +1. **Run the review.** + + ```bash + tools/wikitool review + ``` + + Exit 0 with no findings means a quiet week - say so and stop. A non-zero exit means the report + is **incomplete**: one or more checks could not run because a provider call failed. Read the + printed "INCOMPLETE" block, tell the user which checks were skipped and why, and be explicit + that the *absence* of a finding under a skipped check means nothing - it was never asked. Do + not re-run the command hoping for a different result; a failing provider is not fixed by + retrying. + +2. **Walk the findings by check, one at a time.** Each finding names a `kb/gtd/` project (or, for + the two checks anchored on the tracker side, a tracker project) and the condition that fired. + For every finding, present the options below, ask which applies, and act on the answer - + never pick one yourself. A finding is a question, not an instruction. + + | Check | What fired | Options | How to tell them apart | + |---|---|---|---| + | `stalled` | A tracker project has zero open items and its `kb/` page is `state: active` | (a) A next action is genuinely missing - add one in the tracker. (b) The initiative is deliberately paused - `tools/wikitool touch --page "" --set state=dormant`. (c) It is actually finished or given up on - `--set state=completed` or `--set state=abandoned` | Read the page's `## Ziel` and `## Status` sections and ask the user directly: is there still a next step toward that goal, or did this stop for a reason? A pause that was never decided is (a); a pause that *was* decided is (b), never left as `active` with nothing moving | + | `waiting_overdue` | A `WAITING` item's `follow_up_at` is older than the threshold | (a) Follow up now, then move the reminder forward in the tracker. (b) The commitment is no longer needed - remove or close it in the tracker | Did the person the item names actually come through, and is the ask still relevant? If yes but late, (a); if the need has passed, (b) - never leave the same stale date standing unexamined | + | `unpaged_project` | A tracker project has no `kb/` page, past the age threshold | (a) It has grown a memory worth keeping (participants, decisions, context) - `tools/wikitool new project --name "<Name>" --set responsibility=<area>`. (b) It genuinely never needs one - confirm and leave it tracker-only | Ask: would anyone, including the operator in six months, need to know *why* this exists or who is in it? If yes, (a); a project that is fully explained by its own title and task list stays (b) | + | `no_open_loop` | A `kb/` page is `state: active` but its tracker project is missing or empty | (a) Same three options as `stalled` above. (b) The name diverged - a rename happened on one side only | Before assuming a stall, check whether a *similarly* named tracker project exists. If it does, this is `instructions/page-lifecycle.md`'s rename case (`tools/wikitool rename` for the page, plus renaming the tracker project to match), not a state change - the review reports both directions of a rename so it never has to be inferred silently | + | `someday_stale` | A someday/maybe item has not been touched past the threshold | (a) Activate it - give it a page with `tools/wikitool new project` if it is ready to become a committed initiative. (b) Strike it - remove it from the tracker. (c) Leave it - still genuinely "maybe" | Would the user commit to starting this today? If yes, (a). If it no longer belongs on the list at all, (b). If it is still worth keeping but not yet, (c) is a legitimate answer, not inaction - do not force a decision the user is not ready to make | + +3. **Record what was decided or learned on the page - never the task list.** A decision made this + week (a scope cut, a direction change) goes under `## Entscheidungen`; something that showed + itself in the course of the work goes under `## Gelerntes`. Use `tools/wikitool touch` for the + frontmatter fields it owns (`state`, `summary`, `provenance`) and edit the body directly for + prose, the same as any other page update (`instructions/wiki-manage/SKILL.md` § Updating a + page). **The page never summarizes the open-items list** - that is `kb/gtd/COLLECTION.md`'s + own rule (its momentary state lives in the tracker, joined to the page only by name), and this + skill exists precisely because that join is not automatic. + +4. **Mentions of people stay mentions.** A person named in `## Beteiligte` while working through a + finding does **not** get a page or a `[[wikilink]]`, however much this pass is about them - a + page is earned only once they matter for the knowledge independent of this one initiative + (`types/project.md` § Authoring guidance). Creating one here, out of the habit of linking what + gets mentioned, is the mistake this step exists to head off. + +5. **Close out.** If any page changed, `instructions/publish-cycle.md`. A pass that only changed + tracker state (the user acted on option (a)/(b) above without touching `kb/`) publishes + nothing - there is no page diff to carry. + +## Decision points + +- **A finding's `project` name does not match any page you can find?** That is very likely the + `no_open_loop`/`unpaged_project` rename case in step 2's table, not a data error - check there + before assuming the join is broken. +- **The user wants to skip a finding without deciding?** That is a legitimate outcome for + `someday_stale` (option (c)) and, less often, for a genuinely undecided `stalled` case - leave + it and say so plainly in your summary, rather than silently omitting it. It will resurface next + week. +- **The report was incomplete (step 1)?** Work through whatever findings did arrive; do not treat + a skipped check as reassurance that nothing is wrong there. + +## wikitool commands used + +`review`, `touch`, `new project`, `rename` (via `instructions/page-lifecycle.md`, only for the +rename case), `publish` + +**Deliberately absent:** anything that reaches into the task tracker directly. `review` and +`new project` are the only two GTD commands this stack has (`types/project.md`); every other +tracker-side action in the table above - adding a next action, moving a reminder, removing an +item - is something the user does in their tracker, not something this skill automates. + +## Output + +Tracker-side changes the user made themselves, plus whichever `kb/gtd/` pages actually changed, +published to `origin/main`. + +**Example triggers:** + +- "Let's do the weekly review" +- "What's stalled right now?" diff --git a/tools/chemenu/tests/test_instructions_cmd.py b/tools/chemenu/tests/test_instructions_cmd.py index 0e39825..6c662dc 100644 --- a/tools/chemenu/tests/test_instructions_cmd.py +++ b/tools/chemenu/tests/test_instructions_cmd.py @@ -75,6 +75,25 @@ def test_the_real_repo_publishes_the_six_wiki_skills(): } <= names +def test_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() + forbidden = [ + "super productivity", + "azure devops", + "superproductivity", + "db.json", + "rest api", + ".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}" + + def test_instructions_dev_flat_file_is_discovered(layer): dev_dir = layer / "instructions" / "dev" dev_dir.mkdir()