diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index e464e29..629880b 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -508,4 +508,13 @@ needs-claude --- +## ⚪ [diagnosing-bugs-writing-skills-review] — Review новых скилов `diagnosing-bugs` + `writing-skills` (v0.1.0 оба, не-имплементер сессия). Scope: HARD-GATE не ослаблен (diagnosing: no fixes w/o root cause; writing: no skill w/o failing test); анти-дубль гард (anti-sproul 45+); триггер-дискриминация clean pi -p (коллизии: «зафиксируй» в writing-skills вс гриллинг docs-mode, «почему падает» вс using-vds-ops инциденты); lint/dist/install/pin/README. +**Status:** ready +**Where I stopped:** (not started) +**Next action:** clean-context pi -p субагенты (пос и нег для обоих скилов) + статика; отчёт в .workshop/.brainstorm/diagnosing-bugs-writing-skills-review.md; pull перед push. +**Branch:** n/a +**Notify:** OpeItcLoc03/workshop + + +--- diff --git a/README.md b/README.md index 6d82e19..85e9e38 100644 --- a/README.md +++ b/README.md @@ -117,6 +117,7 @@ an explicit `adapted-from` marker in its frontmatter. | `brainstorming` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — divergent phase, visual-companion dropped | | `diagnosing-bugs` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) + superpowers 6.2.0 concepts (Iron Law, red flags) | | `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — workflow-spec design gate | +| `review-kit-pi-method` | `author: ours` — pi-native spawn for clean-context review subagents | | `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills core + ideya 8 self-skill-authoring | | all other `skills/*` | `author: ours` | diff --git a/README.ru.md b/README.ru.md index ee78bae..c5d5f93 100644 --- a/README.ru.md +++ b/README.ru.md @@ -87,6 +87,7 @@ bash scripts/build.sh caveman # один | `brainstorming` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — расходящаяся фаза, visual-companion выброшен | | `diagnosing-bugs` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) + superpowers 6.2.0 (Iron Law, red flags) | | `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — дизайн-гейт workflow-спец | +| `review-kit-pi-method` | `author: ours` — pi-спавн чистых review-субагентов | | `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills ядро + идея 8 self-skill-authoring | | остальные `skills/*` | `author: ours` | diff --git a/dist/review-kit-pi-method.skill b/dist/review-kit-pi-method.skill new file mode 100644 index 0000000..1085e51 Binary files /dev/null and b/dist/review-kit-pi-method.skill differ diff --git a/skills/review-kit-pi-method/SKILL.md b/skills/review-kit-pi-method/SKILL.md new file mode 100644 index 0000000..76682e3 --- /dev/null +++ b/skills/review-kit-pi-method/SKILL.md @@ -0,0 +1,133 @@ +--- +name: review-kit-pi-method +author: ours +version: 0.1.0 +description: > + Spawn clean-context non-implementer subagents for review, trigger-testing, + and spec validation under pi — the pi-native port of the review-kit method. + Use when reviewing a skill/code/spec by a non-implementer agent, testing + trigger discrimination of skills (clean pi -p subagents), or validating a + workflow spec against loop-me's "implementer asks no questions" criterion. + Triggers: «отдай на ревью», «прогони субагентами», "review with subagents", + «чистый контекст», «непрайменный», trigger-дискриминация. +--- + +# Review-kit under pi + +The review-kit method (clean-context non-implementer subagents) was +claude-centric: spawn subprocesses, keep them unprompted. Under pi the same +method is a `pi -p` invocation with the right flags. This skill pins the exact +command and the anti-priming checklist. + +## The spawn command + +A fully unprompted (clean) subagent: + +```bash +pi -p -nc -ns -nt --no-session "" +``` + +| Flag | Effect | +|---|---| +| `-p` | headless, one-shot | +| `-nc` (`--no-context-files`) | no AGENTS.md / CLAUDE.md loading — the subagent does NOT inherit project rules | +| `-ns` (`--no-skills`) | no skill discovery — it does not know our catalog exists | +| `-nt` (`--no-tools`) | no tools — it cannot read files to self-prompt; answers from model knowledge + the prompt only | +| `--no-session` | ephemeral, nothing persisted | + +Verified live (pi v0.84.1): with `-nc -ns -nt` the subagent reports "no +project-specific instructions" and cannot recite CLAUDE.md rules; without the +flags it can quote them verbatim. The difference is the anti-priming +guarantee: **the review verdict is not contaminated by the reviewer knowing +what the implementer intended.** + +## Anti-priming checklist (per subagent run) + +Before trusting a verdict, confirm the spawn was clean: + +- [ ] `-nc` present — subagent has no context files +- [ ] `-ns` present — subagent has no skills +- [ ] `-nt` present — subagent cannot read files (no self-prompting) +- [ ] `--no-session` — no session bleed +- [ ] The question does NOT name the expected answer, the skill name being + tested, or the files to read (naming them re-primes: e.g. "what does + CLAUDE.md say about X" makes the subagent read it via tools — only + `-nt` blocks that, keep it) + +## Prompting rules + +- **Ask the behavior, not the label.** For trigger tests: "You are given this + user request: «...». Which of your skills would you use, and why?" — never + "does this route to skill X?" (that's leading). +- **One question per run.** A run answers one question; batch by launching + parallel runs, not by cramming. +- **Negative controls matter.** For trigger discrimination, always run phrases + that should NOT match (e.g. «прогриль» must not hit brainstorming). A skill + with 0 false positives on 3-4 negatives is trustworthy. +- **Read every flagged match manually.** Template echoes and quoted + counter-examples masquerade as hits; automated counting alone overstates + both failure and success. + +## When to use which spawn + +| Need | Spawn | +|---|---| +| Trigger discrimination (skill activation) | clean `-nc -ns -nt` | +| Skill/code review by non-implementer | clean `-nc -ns -nt`, plus the review scope in the prompt (what to check, NOT the expected verdict) | +| Spec validation (loop-me criterion) | clean `-nc -ns -nt`, prompt = "given this spec, what would you need to ask before building it?" — any question ⇒ spec not done | +| Context-aware review (reviewer needs project conventions) | WITHOUT `-nc` (let it read CLAUDE.md), but still `-ns -nt --no-session`, and prompt from a neutral third-person role ("a senior engineer reviewing this change") | + +## Pitfalls + +- **Asking "does X trigger skill Y?" primes the answer.** The subagent + cooperates and says yes. Ask what it would do, infer the routing. +- **Naming files in the question lets a tool-enabled subagent read them** — + which is fine when you WANT context, but kills the clean spawn. `-nt` is + the guard. +- **Session bleed:** without `--no-session` a prior run's context can leak. + Always ephemeral. +- **Confirmation bias in the orchestrator:** if the subagent's verdict + contradicts your expectation, report it, don't re-run until it agrees. + Re-running with a re-worded prompt until you like the answer is priming by + another name. +- **Version drift:** pin the pi version in the review report (`pi --version`) + — flag behavior can change between releases. + +## Output convention + +For each subagent run record in the review report: + +``` +- [id] spawn: pi -p -nc -ns -nt --no-session "…" +- [id] prompt: +- [id] verdict: +- [id] reading: +``` + +The report then aggregates: pos/neg counts, false positives with quotes, +conclusion. + +## Relationship to other skills + +- `caveman-review` — output FORMAT (one-line L:line comments), this skill is + the spawn MECHANISM. Use together: spawn clean subagents, format findings + caveman-style. +- `loop-me` — its independent check ("implementer asks no questions") IS a + review-kit spawn with the spec as input. This skill provides the command. +- `diagnosing-bugs` — its sub-agent line ("dispatch a clean-context sub-agent + where your harness supports it") uses this spawn. + +## Cross-agent applicability + +Command is pi-specific by design (this is the pi port). The METHOD — clean +non-implementer subagents, anti-priming checklist, negative controls — is +agent-agnostic and transfers to any runtime that can spawn a fresh-context +subprocess (claude `-p`, codex exec, hermes headless). + +## Out of scope + +- Does NOT define the review criteria themselves (skill-specific acceptance — + see the review task / skill under test). +- Does NOT do the review — it spawns and governs the reviewers. +- Does NOT cover claude-side spawn (that's the legacy method; the pi command + here supersedes it).