Test documentation completeness using blind sub-agents before shipping
Prevent documentation gaps from wasting developer time
Prerequisites:
- Claude Code or compatible AI agent
-
superpowers:dispatching-parallel-agentsskill installed - Documentation you want to validate
Quick Install:
# Clone to your skills directory
git clone https://github.com/whykusanagi/zero-context-validation.git \
~/.claude/skills/zero-context-validation
# Verify installation
ls ~/.claude/skills/zero-context-validation/SKILL.mdBootstrap Checklist:
- ✅ Install skill in your agent's skills directory
- ✅ Prepare documentation to test
- ✅ Define clear implementation task
- ✅ Invoke skill when testing documentation completeness
Built by whykusanagi - VTuber, AI developer, and content creator exploring the intersection of AI agents, documentation quality, and developer experience. Watch AI coding sessions and skill development live on Twitch.
You write documentation that looks complete. You review it and think "this is clear." But when a developer tries to use it, they get blocked:
- Where is this function defined?
- What should this method return?
- Which file should I modify?
- What's the structure of this object?
The gap: What's obvious to you (with context) isn't documented for others (without context).
Zero-Context Validation tests your documentation by spawning blind sub-agents that attempt implementation using ONLY the docs. No prior knowledge, no assumptions, no guessing.
- 🔍 Blind Agent Testing - Fresh agents expose blindspots you can't see
- 🚫 No Assumptions - Missing info must be reported, not guessed
- 🔄 Iterative Improvement - Fix gaps until agents succeed cleanly
- ⏱️ Time Savings - Find gaps before they waste developer time
If the agent gets blocked, you found documentation gaps BEFORE they waste developer time.
Time Investment: 1 hour validation saves 2-4 hours of developer confusion.
You are the main agent with context. Blind sub-agents are your testers.
graph TD
A[Write Documentation] --> B[Spawn Blind Sub-Agent]
B --> C{Agent Attempts Implementation}
C -->|Success, No Assumptions| D[✅ Documentation Complete]
C -->|Reports Gaps| E[Fix Documentation]
C -->|Makes Assumptions| F[Strengthen No-Assumptions Rule]
E --> B
F --> B
style A fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#9f9,stroke:#333,stroke-width:2px
style E fill:#ff9,stroke:#333,stroke-width:2px
style F fill:#f99,stroke:#333,stroke-width:2px
- You prepare: Define what should be implementable from your docs
- You spawn: Launch blind sub-agent that can ONLY use documentation
- Blind agent tests: Attempts implementation or reports gaps
- You judge: Are reported gaps real blindspots in your docs?
- You iterate: Fix docs based on blind agent feedback, re-test
- Success: When blind agent completes without assumptions
Key insight: You can't objectively test your own docs - you know too much. Blind sub-agents expose what's actually missing vs. what you think is obvious.
Main Skill (SKILL.md)
- 500-word reference guide (token efficient)
- Quick Reference table for common situations
- Iron Law enforcement (no assumptions allowed)
- Rationalization table countering common excuses
- Red flags detection for compromised validation
Detailed Examples (examples.md)
- Multi-iteration workflow (3 iterations typical)
- Success vs. failure scenarios
- Gap reporting format templates
- Real development integration patterns
Visual Workflow (workflow.md)
- ASCII diagram of main agent + blind sub-agent loop
- Concrete 3-iteration example
- Integration with development workflow
# Invoke the skill when validating documentation
Use zero-context-validation skill when testing documentation completeness
# The skill guides you through:
1. Setting up the validation task
2. Launching a zero-context agent
3. Analyzing results (blocked = found gaps!)
4. Iterating until docs are complete📋 Operational Guidance
- ✅ Before publishing API documentation
- ✅ After major refactors that change workflows
- ✅ When creating developer onboarding guides
- ✅ Before merging PR with new developer documentation
- ✅ When external developers will use your docs
- ✅ After receiving feedback that docs are "unclear"
The Iron Law: No assumptions allowed. Gaps must be reported, not filled.
Getting blocked is success: When the agent can't proceed, we found gaps before they wasted real developer time.
Pressure resistance: The skill guards against time pressure, authority pressure, and "use your best judgment" traps that cause agents to skip proper validation.
Good outcome:
- Agent implements successfully with zero assumptions, OR
- Agent reports specific gaps we can fix
Bad outcome:
- Agent makes assumptions and invents undocumented details
- We ship incomplete docs thinking they're ready
Goal: Find documentation gaps BEFORE they waste developer time.
Iterative Main Agent + Blind Sub-Agent Loop:
YOU (main agent): Just implemented new Widget API, wrote docs
Iteration 1:
YOU: Spawn blind sub-agent to add premium widget from my docs
BLIND AGENT: "BLOCKED - Missing base class definition"
YOU: "That's a real blindspot! I know Widget but didn't document it."
YOU: Add Widget documentation
Iteration 2:
YOU: Spawn new blind agent with updated docs
BLIND AGENT: "BLOCKED - Missing render() return type"
YOU: "Good catch! I know it returns HTMLElement, forgot to document"
YOU: Add render() contract documentation
Iteration 3:
YOU: Spawn new blind agent
BLIND AGENT: "Implementation complete using only docs!"
YOU: Review - no assumptions made ✅
YOU: Ship documentation ✅Key takeaway: Blind agents expose blindspots you couldn't see because you had context. Multiple iterations are normal and expected!
🔧 Troubleshooting
| Problem | Solution |
|---|---|
| Agent makes assumptions despite skill | Strengthen "no assumptions" instruction, re-test |
| Agent succeeds but invented details | Review implementation, strengthen rules, re-test |
| Authority pressure causes compliance | Remove authority language from instructions |
| Time pressure skips validation | Emphasize validation over speed |
| Can't tell if gaps are real | They probably are - you have context bias |
If you see these, validation is compromised:
- "Using common patterns" for undocumented details
- Creating base classes not in docs
- Inventing file structures/imports
- "Assuming X based on Y"
- Success claimed but invented components
Action: Restart validation with stricter no-assumptions rule.
Traditional approach:
- You review your own documentation
- It looks complete to you (because you have context)
- You unconsciously fill gaps while reading
- Blindspots ship to production
Zero-context validation approach:
- You spawn blind sub-agents to test your docs
- They have zero context - can't fill gaps unconsciously
- They expose actual blindspots in documentation
- You iterate until blind agents succeed
- Only then are docs truly complete
Why this works:
- You know too much to objectively test your own docs
- Blind sub-agents don't know anything, so gaps are obvious to them
- Iterative testing exposes blindspots before they waste developer time
It's like TDD for documentation: Test (blind sub-agent) fails → Fix docs → Test passes → Ship
Issues & Feedback:
- Open an issue for bugs or feature requests
- View existing discussions
Contributing:
- Fork the repository
- Submit pull requests with improvements
- Follow TDD methodology for skill changes (see writing-skills)
Connect with whykusanagi:
Related Resources:
MIT License - Copyright (c) 2026 whykusanagi
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. See the LICENSE file for full details.
🚀 Ready to validate your documentation?
Install the skill and spawn your first blind sub-agent to find gaps before they waste developer time.
git clone https://github.com/whykusanagi/zero-context-validation.git ~/.claude/skills/zero-context-validationInstall Now • View Examples • Read Full Spec
🌐 Website • 📺 Twitch • 🎥 YouTube • 🐦 Twitter • 💬 Discord
Tested with TDD methodology • Validated under pressure • Ready for production