whykusanagi Zero-Context Validation
Overview
Test documentation completeness by spawning blind sub-agents to attempt implementation. They expose blindspots you can't see because you have context.
You orchestrate, judge results, iterate. Blind agents test docs, report gaps.
When to Use
Use: Validating docs before publishing, testing API/setup guides, verifying docs after refactors.
Don't use: Code review, testing code functionality, proof-reading.
Quick Reference
| Situation | Action |
|---|---|
| Just wrote docs | Spawn blind agent with implementation task |
| Agent reports gaps | Judge if real → fix docs → re-test |
| Agent invents details | Strengthen "no assumptions" → re-test |
| Agent succeeds clean | Documentation ready ✅ |
| Multiple iterations | Normal - iterate until clean success |
The Iron Law
NO ASSUMPTIONS ALLOWED. Test agent uses ONLY documentation. Missing info = report gap, not guess.
Violating: Fills gaps → incomplete docs → wasted time.
Process
1. Prepare: Define implementation task for blind agent.
2. Spawn: Launch blind sub-agent using Task tool - ZERO context, ONLY docs, NO assumptions, REPORT gaps.
3. Judge: Succeeds clean → docs ready ✅ | Reports gaps → fix, re-test | Invents → strengthen rules, re-test
4. Iterate: Repeat until success. Multiple iterations normal.
Common Rationalizations (FORBIDDEN)
| Rationalization | Why It Fails |
|---|---|
| "Docs approved by experts" | Approval ≠ tested |
| "Use your best judgment" | Assumptions hide gaps |
| "Common patterns apply" | Document patterns |
| "Implementation successful" (but invented 80%) | Invention ≠ validation |
| "Just a quick sanity check" | Review misses gaps |
Re-run with no-assumptions enforced.
Red Flags - STOP Validation
- "Using common patterns" for undocumented details
- Creating base classes not in docs
- Inventing file structures/imports
- "Assuming X based on Y"
- Success but invented components
- Instructions include "use best judgment"
Validation invalid. Restart with stricter rules.
Success Metrics
Good: Agent succeeds with zero assumptions OR reports gaps. Bad: Agent invents details. Goal: Find gaps before wasting developer time.
Common Mistakes
| Mistake | Fix |
|---|---|
| "Just review, don't implement" | Require implementation attempt |
| Including context in instructions | Fresh agent, docs only |
| Allowing "reasonable assumptions" | Forbid assumptions, require reports |
| Authority pressure ("approved by experts") | Neutral instructions |
| Treating blocked agents as failure | Blocked = found gaps |
Impact
Without: Docs look complete → publish → blocked developers. With: Test docs → find gaps → fix → ship complete.
1 hour validation saves 2-4 hours confusion.
Example
Typical workflow: 3 iterations to find and fix gaps. See examples.md for detailed multi-iteration workflow.
Related Skills
- superpowers:test-driven-development - Same principles, applied to docs
- superpowers:writing-skills - Testing skills uses same validation
Technical Implementation
Uses the built-in Task tool to spawn blind sub-agents. No external dependencies required.