| name | exhaustive-specification |
| description | Write exhaustive specifications for autonomous AI systems that leave nothing to chance, covering every detail from UI to database schemas with adversarial refinement |
| license | MIT |
| compatibility | opencode |
| metadata | {"audience":"ai-engineers, system-architects, product-managers","category":"documentation"} |
Exhaustive Specification Writing
Write exhaustive specifications for autonomous AI systems that leave nothing to chance. Create specs so detailed that a blind person could visualize the entire system. Uses _prompt.md for consistency and _index.md for tracking - context can be lost and restored without losing spec direction.
When to use me
Use this skill when:
- You need specifications for autonomous AI agents to build complete systems without human intervention
- Current AI-generated specs are insufficiently detailed and leave critical aspects ambiguous
- You're building complex systems where every detail matters
- You want specs that survive context loss through
_prompt.md and _index.md
- You need to map out ALL spec types before writing begins
Core Architecture
flowchart TB
subgraph "Initialization"
START[Start Project] --> MAP[Map Spec Types]
MAP --> PROMPT[Create _prompt.md]
MAP --> INDEX[Create _index.md]
MAP --> TEMPLATES[Create Templates]
end
subgraph "Specification Files"
PROMPT --> |"Defines Detail Level"| SPECS[Spec Files]
INDEX --> |"Tracks Progress"| SPECS
TEMPLATES --> |"Provides Structure"| SPECS
end
subgraph "Context Recovery"
LOST[Context Lost] --> READ[Read _prompt.md]
READ --> READ2[Read _index.md]
READ2 --> RESUME[Resume Writing]
end
Three Core Files
1. _prompt.md - The Base Prompt
The canonical prompt that defines the level of detail for ALL specs. Every spec generated uses this as the foundation.
Location: specs/_prompt.md
Purpose:
- Ensures consistent detail level across all specs
- Survives context loss - new sessions read this to maintain quality
- Defines the "exhaustive standard" for the project
# Exhaustive Specification Prompt
## Detail Level Standard
**BLIND-PERSON VISUALIZATION**: Write specs so detailed that someone who cannot see can fully visualize the system. Every UI element, animation, color, interaction must be described in prose.
**NO ASSUMPTIONS**: Every decision must be explicit. Never write "as discussed" or "standard practice". Define everything.
**EXHAUSTIVE COVERAGE**:
- Happy path + ALL error paths
- All edge cases enumerated
- All timing, sizing, spacing specified
- All states and transitions documented
- All data transformations explained
## Writing Standards
### For UI/UX Specs
- Exact pixel dimensions, colors (hex codes), fonts
- Animation timing (ms), easing functions
- Responsive breakpoints
- Accessibility requirements (WCAG level)
- Error states, loading states, empty states
### For API Specs
- Request/response schemas with examples
- All error codes with causes and resolutions
- Rate limits, timeouts, retry behavior
- Authentication/authorization for each endpoint
- Idempotency requirements
### For Database Specs
- Complete schema with constraints
- Index strategy and rationale
- Query patterns with example queries
- Migration strategies
- Backup/recovery procedures
### For Logic Specs
- Step-by-step algorithms
- Decision trees for all branches
- Input validation at each step
- State machines with all transitions
- Error handling at each step
## Structure Template
Every spec follows this structure:
- What this component does
- What it requires
- How it interacts with other components
- Detailed logic (happy path + error paths)
- Data structures, schemas
- All possible states and transitions
- All error conditions and handling
- Test cases to validate
- Security considerations
- Performance requirements
Before marking any spec complete:
[ ] Can a blind person visualize this from the description?
[ ] Is every assumption explicitly stated?
[ ] Are all error paths documented?
[ ] Are all edge cases enumerated?
[ ] Is there an example for every data structure?
[ ] Are all timings/sizings specified with units?
2. _index.md - The Spec Index
Tracks all specs in the system with status, dependencies, and completeness.
Location: specs/_index.md
Purpose:
- Single source of truth for what specs exist
- Tracks completion status
- Maps dependencies between specs
- Enables context recovery - know exactly what to continue
# Specification Index
**Project**: [Project Name]
**Last Updated**: YYYY-MM-DD
**Total Specs**: 12
**Completed**: 8
**In Progress**: 2
**Pending**: 2
## Spec Registry
| ID | Spec File | Category | Status | Dependencies | Lines | Last Modified |
|----|-----------|----------|--------|--------------|-------|---------------|
| S01 | 01-system-overview.md | Core | ✅ Complete | None | 1,234 | 2026-03-24 |
| S02 | 02-ui-main.md | UI | ✅ Complete | S01 | 3,456 | 2026-03-24 |
| S03 | 03-ui-modals.md | UI | 🔄 In Progress | S01, S02 | 892 | 2026-03-24 |
| S04 | 04-api-auth.md | API | ✅ Complete | S01 | 2,345 | 2026-03-23 |
| S05 | 05-api-users.md | API | ✅ Complete | S01, S04 | 1,876 | 2026-03-23 |
| S06 | 06-api-orders.md | API | 🔄 In Progress | S01, S05 | 456 | 2026-03-24 |
| S07 | 07-database-schema.md | Database | ✅ Complete | S01 | 2,789 | 2026-03-22 |
| S08 | 08-database-migrations.md | Database | ✅ Complete | S07 | 987 | 2026-03-22 |
| S09 | 09-security.md | Security | ✅ Complete | S01, S04, S07 | 1,567 | 2026-03-21 |
| S10 | 10-deployment.md | Operations | ⏳ Pending | All | 0 | - |
| S11 | 11-performance.md | Operations | ⏳ Pending | S02, S05, S07 | 0 | - |
| S12 | 12-testing.md | QA | ✅ Complete | All | 4,567 | 2026-03-24 |
## Dependency Graph
S01 (Overview)
├── S02 (UI Main) ──┬── S03 (UI Modals)
│ │
├── S04 (API Auth) ─┼── S05 (API Users) ──┬── S06 (API Orders)
│ │ │
├── S07 (DB Schema) ─┼── S08 (DB Migrations)
│ │
├── S09 (Security) ─┘
│
└── S10 (Deployment) [needs all]
└── S11 (Performance) [needs S02, S05, S07]
S12 (Testing) [needs all]
## Categories
### Core (1 spec)
- [x] S01: System Overview
### UI (2 specs)
- [x] S02: Main UI
- [ ] S03: Modal Components (in progress)
### API (3 specs)
- [x] S04: Authentication API
- [x] S05: Users API
- [ ] S06: Orders API (in progress)
### Database (2 specs)
- [x] S07: Database Schema
- [x] S08: Migrations
### Security (1 spec)
- [x] S09: Security Specification
### Operations (2 specs)
- [ ] S10: Deployment (pending)
- [ ] S11: Performance (pending)
### QA (1 spec)
- [x] S12: Testing Strategy
## Next Actions
1. Complete S03: UI Modals (blocking: S03)
2. Complete S06: Orders API (blocking: S06)
3. Start S10: Deployment (blocked by: S03, S06)
4. Start S11: Performance (blocked by: S03, S06)
5. Update S12: Testing after all specs complete
## Notes
- S03 blocked on modal animation specs
- S06 needs error handling for order states
- S12 needs to be updated after S10, S11 complete
3. Spec Type Templates
Pre-defined templates for each spec type ensure nothing is missed.
Spec Type Mapping
Tier 1: Foundation Specs (Start Here)
| ID | Spec Type | Purpose | Template File |
|---|
| S01 | System Overview | Project purpose, architecture, success criteria | templates/01-system-overview.md |
| S02 | Domain Model | Entities, value objects, aggregates | templates/02-domain-model.md |
| S03 | Glossary | Terms, definitions, domain language | templates/03-glossary.md |
Tier 2: UI/UX Specs
| ID | Spec Type | Purpose | Template File |
|---|
| U01 | UI Layout | Page layouts, components, responsive | templates/u01-ui-layout.md |
| U02 | UI Flows | User journeys, state transitions | templates/u02-ui-flows.md |
| U03 | UI Components | Buttons, forms, modals, cards | templates/u03-ui-components.md |
| U04 | UI Animations | Transitions, micro-interactions | templates/u04-ui-animations.md |
| U05 | UI Accessibility | ARIA, keyboard nav, screen readers | templates/u05-ui-accessibility.md |
| U06 | UI Error States | Validation, error messages, recovery | templates/u06-ui-error-states.md |
Tier 3: API Specs
| ID | Spec Type | Purpose | Template File |
|---|
| A01 | API Overview | Endpoints summary, versioning, authentication | templates/a01-api-overview.md |
| A02 | API Authentication | Auth flows, token management | templates/a02-api-auth.md |
| A03 | API Resources | CRUD endpoints for each resource | templates/a03-api-resources.md |
| A04 | API Errors | Error codes, messages, recovery | templates/a04-api-errors.md |
| A05 | API Rate Limiting | Throttling, quotas, backoff | templates/a05-api-rate-limiting.md |
| A06 | API Webhooks | Events, payloads, retry logic | templates/a06-api-webhooks.md |
Tier 4: Data Specs
| ID | Spec Type | Purpose | Template File |
|---|
| D01 | Database Schema | Tables, columns, constraints, indexes | templates/d01-database-schema.md |
| D02 | Database Queries | Query patterns, optimization | templates/d02-database-queries.md |
| D03 | Database Migrations | Version history, upgrade paths | templates/d03-database-migrations.md |
| D04 | Data Validation | Input validation, sanitization | templates/d04-data-validation.md |
| D05 | Data Retention | Archival, deletion, compliance | templates/d05-data-retention.md |
Tier 5: Business Logic Specs
| ID | Spec Type | Purpose | Template File |
|---|
| B01 | Business Rules | Invariants, constraints, calculations | templates/b01-business-rules.md |
| B02 | State Machines | Entity states, transitions, guards | templates/b02-state-machines.md |
| B03 | Workflows | Multi-step processes, orchestration | templates/b03-workflows.md |
| B04 | Calculations | Formulas, algorithms, rounding | templates/b04-calculations.md |
| B05 | Notifications | Email, push, in-app alerts | templates/b05-notifications.md |
Tier 6: Cross-Cutting Specs
| ID | Spec Type | Purpose | Template File |
|---|
| X01 | Security | AuthZ, encryption, vulnerabilities | templates/x01-security.md |
| X02 | Logging | Events, levels, formats, retention | templates/x02-logging.md |
| X03 | Monitoring | Metrics, dashboards, alerts | templates/x03-monitoring.md |
| X04 | Error Handling | Global error handling, recovery | templates/x04-error-handling.md |
| X05 | Configuration | Env vars, feature flags, secrets | templates/x05-configuration.md |
Tier 7: Operations Specs
| ID | Spec Type | Purpose | Template File |
|---|
| O01 | Deployment | CI/CD, environments, rollbacks | templates/o01-deployment.md |
| O02 | Infrastructure | Servers, containers, networking | templates/o02-infrastructure.md |
| O03 | Performance | Benchmarks, load testing, SLAs | templates/o03-performance.md |
| O04 | Backup & Recovery | Backups, disaster recovery | templates/o04-backup-recovery.md |
| O05 | Runbooks | Incident response, maintenance | templates/o05-runbooks.md |
Tier 8: Quality Specs
| ID | Spec Type | Purpose | Template File |
|---|
| Q01 | Test Strategy | Coverage, types, automation | templates/q01-test-strategy.md |
| Q02 | Test Cases | Specific test scenarios | templates/q02-test-cases.md |
| Q03 | Acceptance Criteria | Definition of done | templates/q03-acceptance-criteria.md |
| Q04 | Quality Gates | Review checkpoints | templates/q04-quality-gates.md |
Tier 9: Integration Specs
| ID | Spec Type | Purpose | Template File |
|---|
| I01 | Third-Party Integrations | External service contracts, SLAs | templates/i01-integrations.md |
| I02 | API Versioning | Version strategy, deprecation policy | templates/i02-api-versioning.md |
| I03 | Feature Flags | Rollout strategies, kill switches | templates/i03-feature-flags.md |
| I04 | Webhook Receivers | Inbound webhooks, verification | templates/i04-webhook-receivers.md |
| I05 | Event Schema Registry | Event schemas, versioning | templates/i05-event-schema.md |
Tier 10: Mobile Specs
| ID | Spec Type | Purpose | Template File |
|---|
| M01 | Mobile Overview | Platform-specific considerations | templates/m01-mobile-overview.md |
| M02 | Mobile Navigation | Screen flows, gestures | templates/m02-mobile-navigation.md |
| M03 | Mobile Components | Native UI components | templates/m03-mobile-components.md |
| M04 | Mobile Offline | Sync strategies, conflict resolution | templates/m04-mobile-offline.md |
| M05 | Push Notifications | Push specs, delivery handling | templates/m05-push-notifications.md |
Tier 11: AI/ML Specs
| ID | Spec Type | Purpose | Template File |
|---|
| AI01 | Model Cards | Model purpose, limitations, biases | templates/ai01-model-cards.md |
| AI02 | Training Pipelines | Data ingestion, preprocessing | templates/ai02-training-pipelines.md |
| AI03 | Model Serving | Inference endpoints, versioning | templates/ai03-model-serving.md |
| AI04 | Feature Engineering | Feature definitions, transformations | templates/ai04-feature-engineering.md |
| AI05 | Model Monitoring | Drift detection, retraining triggers | templates/ai05-model-monitoring.md |
Tier 12: DevOps/SRE Specs
| ID | Spec Type | Purpose | Template File |
|---|
| SRE01 | SLIs/SLOs/SLAs | Service level definitions | templates/sre01-slo.md |
| SRE02 | Incident Management | Incident response procedures | templates/sre02-incidents.md |
| SRE03 | On-Call Procedures | On-call rotation, escalation | templates/sre03-oncall.md |
| SRE04 | Chaos Engineering | Failure injection, resilience tests | templates/sre04-chaos.md |
| SRE05 | Capacity Planning | Growth projections, scaling | templates/sre05-capacity.md |
Tier 13: Localization Specs
| ID | Spec Type | Purpose | Template File |
|---|
| L01 | Locale Support | Supported locales, fallback chains | templates/l01-locale-support.md |
| L02 | String Management | Translation keys, placeholders | templates/l02-string-management.md |
| L03 | Cultural Adaptation | Date/time formats, RTL support | templates/l03-cultural-adaptation.md |
| L04 | Content Localization | Images, colors, cultural considerations | templates/l04-content-localization.md |
Tier 14: Data Engineering Specs
| ID | Spec Type | Purpose | Template File |
|---|
| DE01 | Data Pipelines | ETL/ELT workflows | templates/de01-data-pipelines.md |
| DE02 | Data Quality | Validation, cleansing, profiling | templates/de02-data-quality.md |
| DE03 | Data Lineage | Source tracking, impact analysis | templates/de03-data-lineage.md |
| DE04 | Data Governance | Data catalog, ownership, retention | templates/de04-data-governance.md |
| DE05 | Caching Strategy | Cache levels, invalidation, TTL | templates/de05-caching-strategy.md |
Tier 15: Real-Time Specs
| ID | Spec Type | Purpose | Template File |
|---|
| RT01 | WebSocket Connections | Connection lifecycle, auth | templates/rt01-websockets.md |
| RT02 | Real-Time Events | Event types, subscriptions | templates/rt02-realtime-events.md |
| RT03 | Presence & Status | Online/offline, typing indicators | templates/rt03-presence.md |
| RT04 | Collaboration | Concurrent editing, conflict resolution | templates/rt04-collaboration.md |
Tier 16: Analytics Specs
| ID | Spec Type | Purpose | Template File |
|---|
| AN01 | Event Tracking | User events, metrics definition | templates/an01-event-tracking.md |
| AN02 | User Analytics | Behavior tracking, funnels | templates/an02-user-analytics.md |
| AN03 | Business Metrics | KPIs, reporting requirements | templates/an03-business-metrics.md |
| AN04 | Dashboards | Metric visualization, alerts | templates/an04-dashboards.md |
Tier 17: Security Enhanced Specs
| ID | Spec Type | Purpose | Template File |
|---|
| SEC01 | Threat Modeling | STRIDE analysis, attack surfaces | templates/sec01-threat-modeling.md |
| SEC02 | Secrets Management | Key rotation, scope, storage | templates/sec02-secrets-management.md |
| SEC03 | Compliance Mapping | GDPR, HIPAA, SOC 2 requirements | templates/sec03-compliance.md |
| SEC04 | Audit Trail | Immutable logs, retention | templates/sec04-audit-trail.md |
Workflow
Phase 1: Initialize
bash scripts/init-specs-structure.sh --project "My Project"
Phase 2: Map Specs
bash scripts/map-required-specs.sh --analyze
Phase 3: Generate Specs
bash scripts/generate-spec.sh --spec-id S01 --from-template
bash scripts/generate-spec.sh --all-pending
Phase 4: Validate
bash scripts/validate-spec.sh --spec-id S01
bash scripts/validate-spec.sh --all
bash scripts/update-index.sh
Context Recovery
When context is lost, restore by:
sequenceDiagram
participant AI as AI Agent
participant FS as File System
participant WORK as Work Resume
Note over AI,WORK: Context Lost
AI->>FS: Read specs/_prompt.md
FS-->>AI: Base prompt standard
AI->>FS: Read specs/_index.md
FS-->>AI: All specs + status
AI->>FS: Read in-progress spec
FS-->>AI: Current spec content
AI->>WORK: Resume writing
- Read
specs/_prompt.md → Know the detail standard
- Read
specs/_index.md → Know what exists and what's pending
- Read the in-progress spec → Continue where left off
- Resume writing with full context
Scripts
| Script | Purpose |
|---|
init-specs-structure.sh | Create directory and core files |
map-required-specs.sh | Analyze what specs are needed |
generate-spec.sh | Generate spec from template |
validate-spec.sh | Validate spec completeness |
update-index.sh | Update the spec index |
run-adversarial-refinement.sh | Apply adversarial patterns |
Integration with Other Skills
- @skills/adversarial-thinking: Refinement patterns
- @skills/notebooklm-federated-specs: Storage and querying
- @skills/data-flow-architect: Data flow documentation
- @skills/api-documentation: API specs
Notes
- _prompt.md is sacred: Defines quality standard
- _index.md is truth: Single source of spec status
- Templates ensure completeness: Never miss a spec type
- Context recovery is built-in: Read two files, resume work
- Map before writing: Know all specs needed before starting
