superpowers-mcp 6.3.5 → 6.3.7

package/skills/verification-before-completion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verification-before-completion
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; for work with no test command (reports, research, recipes, correspondence, audits) requires re-opening the artifact and accounting for every part of the request; evidence before assertions always
 ---
 
 # Verification Before Completion
@@ -118,3 +118,56 @@ Skip any step = lying, not verifying
 - Paraphrases and synonyms
 - Implications of success
 - ANY communication suggesting completion/correctness
+
+---
+
+## When There Is No Test Command
+
+### Why this section exists
+
+Everything above assumes an external judge: a test suite, a linter, an exit code.
+The machine says pass or fail and you cannot argue with it.
+
+Most work has no such judge. Nothing can run a report, a recipe or a research
+answer and return "correct". The rule does not change — **no completion claim
+without evidence** — only what evidence means.
+
+### The failure this stops
+
+Reporting what you INTENDED to produce rather than what is actually on disk.
+
+**If you have not re-opened the artifact in this message, you have not checked
+it.** You are remembering your own intentions, which is exactly the state in
+which things get missed.
+
+### Two levels, in this order
+
+#### 1. Prove whatever CAN be proven
+
+Some things are as binary as a test suite:
+
+| Claim | Evidence |
+|---|---|
+| Followed the required structure | Open the file. Name each required section and where it appears. |
+| Sources cited | Every claim carries a reference, present and in the required format |
+| Standing constraints held | Re-read start to finish. A constraint honoured in step 1 and dropped in step 8 is a failure. |
+| Findings are real | Every finding points at a location — a line, a quoted span. A finding with no location was recalled, not read. |
+| Data reconciles | Totals add up; numbers in the summary match numbers in the table |
+| Nothing was truncated | The output ends where it should, not mid-section |
+
+#### 2. For everything else, account for the request in full
+
+- Break what was asked into its separate parts.
+- Open what you actually produced.
+- Confirm each part is addressed.
+- **State plainly anything you did not do.**
+
+Four of five things done is not "done". Say which four.
+
+### What this does NOT claim
+
+Confirming that work is complete, consistent and within spec does not make it
+correct. A recipe can hang together perfectly and still taste wrong; a report can
+follow its structure and still reach the wrong conclusion.
+
+**Say which you verified: that the work is *complete*, not that it is *right*.**

package/skills/writing-plans/SKILL.md

@@ -179,15 +179,30 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 
 ## Execution Handoff
 
-After saving the plan, offer execution choice:
+After saving and self-reviewing the plan, link it for your human partner
+to read. If they have already explicitly supplied an execution method, ask
+them to review the plan and confirm it captures what they want; wait for that
+review before implementation, then use the preserved method. Otherwise, ask
+them to review the plan and choose an execution method before implementation.
 
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
+**When no execution method has already been supplied:**
 
-**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Two execution options:**
 
-**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+**1. Subagent-Driven** - fresh subagent per task, review between tasks, fast iteration
 
-**Which approach?"**
+**2. Inline Execution** - tasks in a session via executing-plans, batched with checkpoints
+
+**Recommended for this plan: [pick one] — [one-line why].** Then: **Does the plan capture what you want, and which approach should we use?"**
+
+Pick the recommendation from the plan in front of you:
+- **Subagent-driven** when tasks are largely independent, the plan is short-to-medium, and a cold executor could pick up each task from its own task block alone.
+- **Inline** when tasks share interfaces/state, build heavily on each other, the plan is long, or you (the parent) already hold the spec/architecture context that a cold subagent would spend a spawn re-deriving each time.
+Say which and why. Never default to one without looking.
+
+**When an execution method has already been supplied:**
+
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Does it capture what you want?"**
 
 **If Subagent-Driven chosen:**
 - **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development

package/skills/writing-skills/SKILL.md

@@ -371,6 +371,35 @@ pptx/
 ```
 When: Reference material too large for inline
 
+### Moving Content Into a Skill
+
+Relative paths mean nothing on their own - they resolve against the file holding them. Moving content to a different depth invalidates every relative reference inside it.
+
+**Re-resolve links mechanically, never by counting `../` by eye:**
+
+```bash
+# From the moved file's directory, assert every relative target exists
+d=$(dirname "$FILE")
+grep -o ']([^)]*)' "$FILE" | sed 's/^](//;s/)$//' | while read -r l; do
+  case "$l" in http*|\#*|mailto:*|"") continue;; esac
+  [ -e "$d/${l%%#*}" ] || echo "DANGLING: $l"
+done
+```
+
+A link that is one `../` short still renders as a link. The count is not something you verify by looking at it.
+
+Read the output - this is a heuristic, not a parser, so `](` inside a fenced code block shows up as a false positive.
+
+**Then grep the moved text for prose cross-references:**
+
+```bash
+grep -n 'above\|below\|earlier\|later' "$FILE"
+```
+
+"The section above" has no referent once that section lives in a different file. No link checker can catch this - only reading can.
+
+**Why this matters:** a dangling link fails silently. The agent follows it, finds nothing, and proceeds without the context it was supposed to have. No error, no failing test.
+
 ## The Iron Law (Same as TDD)
 
 ```
@@ -660,6 +689,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 - [ ] Common mistakes section
 - [ ] No narrative storytelling
 - [ ] Supporting files only for tools or heavy reference
+- [ ] Content moved from another file: every relative link re-resolved against the new location and verified to exist; prose cross-references (`above`, `below`, `earlier`, `later`) re-read for lost referents
 
 **Deployment:**
 - [ ] Commit skill to git and push to your fork (if configured)