mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
1a3bfae784
Based on OPENSPEC_COMPREHENSIVE_RETROSPECTIVE.md analysis: Added critical missing documentation: - Scenario formatting requirements (#### Scenario: headers) - #1 pain point - Complete spec file structure examples with ADDED/MODIFIED sections - Delta file location and extraction explanation - Debugging commands (show --json --deltas-only) - Troubleshooting section with common errors and solutions Expanded implementation: - Added 2 new task sections (Spec File Documentation, Troubleshooting) - Increased from 41 to 52 total implementation tasks - Added critical items to CLAUDE.md template tasks This directly addresses the retrospective's top issues: 1. Scenario format documentation (marked "COMPLETELY MISSING") 2. Complete spec file examples 3. Delta detection debugging 4. Silent parsing failure explanations
5.1 KiB
5.1 KiB
Design: Agent Instructions Update
Approach
Information Architecture
- Front-load critical information - Three-stage workflow comes first
- Clear hierarchy - Core Workflow → Quick Start → Commands → Details → Edge Cases
- 50% length reduction - Target ~285 lines from current ~575 lines
- Imperative mood - "Create proposal" vs "You should create a proposal"
- Bullet points over paragraphs - Scannable, concise information
Three-Stage Workflow Documentation
The workflow is now prominently featured as a core concept:
- Creating - Proposal generation phase
- Implementing - Code development phase with explicit steps:
- Read proposal.md for understanding
- Read design.md for technical context
- Read tasks.md for checklist
- Implement tasks sequentially
- Mark complete immediately after each task
- Archiving - Post-deployment finalization phase
This structure helps agents understand the lifecycle and their role at each stage. The implementation phase is particularly detailed to prevent common mistakes like skipping documentation or batching task completion.
CLI Documentation Updates
- Comprehensive command coverage - All 9 primary commands documented
openspec listprominence - Essential for discovering changes and specs- Interactive mode documentation - How agents can use prompts effectively
- Complete flag documentation - All options like --json, --type, --skip-specs
- Deprecation cleanup - Remove noun-first patterns (openspec change show)
Agent-Specific Enhancements
Based on industry best practices for coding agents (Claude Code, Cursor, etc.):
Implementation Workflow
- Explicit steps prevent skipping critical context
- Reading proposal/design first ensures understanding before coding
- Sequential task completion maintains focus
- Immediate marking prevents losing track of progress
- Addresses common failure mode: jumping straight to code
Spec Discovery Workflow
- Always check existing specs before creating new ones
- Use
openspec list --specsto discover current capabilities - Prefer modifying existing specs over creating duplicates
- Prevents fragmentation and maintains coherent architecture
Decision Clarity
- Clear decision trees eliminating ambiguous conditions
- Concrete examples for each decision branch
- Simplified bug vs feature determination
Tool Usage Guidance
- Tool selection matrix (when to use Grep vs Glob vs Read)
- Error recovery patterns for common failures
- Verification workflows to confirm correctness
Context Management
- "Before Any Task" checklist for gathering context
- What to read before starting any work
- How to maintain state across interactions
Spec File Structure Documentation
- Complete examples with ADDED/MODIFIED/REMOVED sections
- Critical scenario formatting (#### Scenario: headers)
- Delta file location clarity (changes/{name}/specs/)
- Addresses most common creation errors from retrospective
Troubleshooting and Debugging
- Common error messages with solutions
- Delta detection debugging steps
- Validation best practices
- JSON output for inspection
- Prevents hours of frustration from silent failures
Best Practices
- Be concise (one-line answers when appropriate)
- Be specific (file.ts:42 line references)
- Start simple (<100 lines, single-file defaults)
- Justify complexity (require metrics/data)
Design Rationale
Why These Changes Matter
Cognitive Load Reduction
- Agents process instructions better with clear structure
- Front-loading critical info reduces scanning time
- Decision trees eliminate analysis paralysis
Industry Alignment
- Follows patterns proven effective in Claude Code, Cursor, GitHub Copilot
- Addresses common failure modes (ambiguous decisions, missing context)
- Optimizes for LLM strengths (pattern matching) vs weaknesses (calculations)
Addressing Critical Pain Points (from Retrospective)
- Scenario formatting - Biggest struggle, now explicitly documented with examples
- Complete spec structure - Full examples prevent structural errors
- Delta detection issues - Debugging commands help diagnose problems
- Silent parsing failures - Troubleshooting section explains common issues
Practical Impact
- Faster agent comprehension of tasks
- Fewer misinterpretations of requirements
- More consistent implementation quality
- Better error recovery when things go wrong
- Prevents the most common errors identified in user experience
Trade-offs
What We're Removing
- Lengthy explanations of concepts that can be inferred
- Redundant examples that don't add clarity
- Verbose edge case documentation (moved to reference section)
- Deprecated command documentation
What We're Keeping
- All critical workflow steps
- Complete CLI command reference
- Complexity management principles
- Directory structure visualization
- Quick reference summary
Implementation Notes
The CLAUDE.md template is intentionally more concise than README.md since:
- It appears in every project root
- Agents can reference the full README.md for details
- It needs to load quickly in AI context windows
- Focus is on immediate actionable guidance