diff --git a/plugin/skills/using-scribe/SKILL.md b/plugin/skills/using-scribe/SKILL.md index bb498c3..140089c 100644 --- a/plugin/skills/using-scribe/SKILL.md +++ b/plugin/skills/using-scribe/SKILL.md @@ -125,6 +125,24 @@ Two constraints on *how* that's achieved: worth reading while almost nothing is on it, so a check added out of tidiness costs the whole surface, not just that note. + **The sharper form of the same test: is the thing this note describes yours + to change?** If yes it is a decision — editing your own software is how it + changes, and you will know you did it. Measured against a real corpus, every + note that earned a check was about somebody ELSE's software: a signing + service, a forge, a hub, an SDK, a model, a dependency set. + + **Three that look like candidates and are not:** + - **Resume pointers and "current state" notes.** They go stale fastest of + anything, which is exactly why they tempt — but the cure is to update or + delete them, not to schedule a check. A sweep full of pointers is a sweep + nobody reads. + - **Measurements of your own system.** They go false because you changed + something, and you knew. A measurement earns a check only when what it + measures is outside your control. + - **A decision that RESTS on somebody else's behaviour.** The decision is + still a decision. Put the check on the note asserting the fact, and link + the decision to it. + Not for tasks — a task's decay is its status, and a done issue records what happened rather than asserting something that can go false. Not for snippets either: `verify_snippet` compares the recorded location and code against the diff --git a/src/scribe/mcp/tools/notes.py b/src/scribe/mcp/tools/notes.py index 9b0aa9f..24843cc 100644 --- a/src/scribe/mcp/tools/notes.py +++ b/src/scribe/mcp/tools/notes.py @@ -147,7 +147,16 @@ async def create_note( and it goes false with nobody watching. Only constraints get a check. The test, in one question: COULD THIS NOTE BECOME FALSE WITHOUT - ANYONE EDITING IT? If no, leave this empty. + ANYONE EDITING IT? If no, leave this empty. Sharper still: is the + thing this note describes YOURS TO CHANGE? If yes it is a + decision. Measured against a real corpus, every note that earned a + check was about somebody else's software. + Three that look like candidates and are not: a resume pointer or + "current state" note (goes stale fastest, but the cure is to + update it, not to check it); a measurement of your own system (it + goes false because you changed something, and you knew); and a + decision that RESTS on someone else's behaviour (check the note + asserting the fact, not the decision). A command, a path, a URL, a query. Prose is allowed; something runnable is better. expires_when: The STATE that ends it — deliberately not a date.