sisyphus-plan-writer

name	sisyphus-plan-writer
description	Create YAML format work plans saved as .sisyphus/tasks/{name}.yaml with strict schema validation. Analyze user requirements, gather project context, and generate structured plans with verification specs. ALWAYS includes mandatory plan-reviewer verification. Use when users request YAML-based work planning or Sisyphus-compatible task breakdown.

Plan Writer (YAML)

Create systematic, actionable work plans in YAML format* by analyzing user requirements and project context. Every plan is automatically reviewed by plan-reviewer agent before finalization.

ALWAYS START BY FOLLOWING

Before starting any plan creation work, use the TodoWrite tool to register all upcoming steps:

Use TodoWrite to create todos for the following:
1. Analyze user request and decide: single plan vs multiple plans (CRITICAL FIRST DECISION)
2. Present decomposition decision to user and get confirmation
3. Initialize YAML file(s) with sisyphus-speckit plan init (N times based on decision)
4. Capture user request in YAML file(s)
5. Clarify and refine user requirements (5 essential questions)
6. Gather implementation context via massive parallel information gathering
7. Complete YAML work plan(s)
8. Request sisyphus-plan-reviewer verification (MANDATORY)
9. Incorporate reviewer feedback and iterate until "OKAY"
10. Run sisyphus-speckit plan lint --file {path} to validate YAML schema (MANDATORY)
11. Fix any linter errors and re-lint until PASSED

Mark each step as 'pending' initially, then update to 'in_progress' and 'completed' as you work through them.

!!MUST!! !!ALWAYS FIRST!! Init the plan file

Always init the plan file before starting the plan creation work.

sisyphus-speckit plan init --path .sisyphus/tasks/{name}.yaml --initial-request {{what user said}}

And then write down the user's initial request in the plan file - mandatory. the very first thing.

Core Principles

The 99%+ Explicitness Standard

Every task must provide 99%+ implementation confidence using ONLY the plan document and explicitly referenced sections.

This means:

• Workers should NOT need codebase exploration or guesswork
• All necessary context, references, and examples are embedded in the plan OR provided via structured references
• Information is either explicit in plan OR explicitly referenced with file + line numbers + key points
• Ambiguity is minimized to ≤1% (only standard language syntax and core framework APIs)

NOT acceptable: "Worker can discover this through code exploration" ACCEPTABLE: "See auth/login.ts:20-45 for OAuth flow (key: token exchange at line 28, session storage at line 35)"

Planning Standards

1. Big Picture First (WHY, WHAT, HOW)

   • WHY: Purpose statement (business value, user problem to solve)
   • WHAT: Background context (current state → what we're changing)
   • HOW: Task flow (dependencies, sequence, logical connections)
   • Success Vision: End state from product/user perspective (not just "code works")

2. Test-First Planning (MANDATORY - CRITICAL FOR PLAN-REVIEWER APPROVAL)

   • CRITICAL: Every implementation task MUST be followed by a corresponding test task
   • Test tasks are NOT optional - plan-reviewer will AUTOMATICALLY REJECT plans without tests
   • Test tasks must clearly specify:
     • What behaviors/scenarios to test
     • Expected outcomes for each test case
     • Test types (unit, integration, e2e) where applicable
   • Include automated verification (bash command or llm_judge)
   • Interleave test tasks with implementation (don't defer all testing to the end)

3. Commit Planning (MANDATORY - CRITICAL FOR PLAN-REVIEWER APPROVAL)

   • CRITICAL: Multi-step implementations MUST include explicit commit checkpoint tasks
   • Commit tasks are NOT optional - plan-reviewer will AUTOMATICALLY REJECT plans without commit strategy
   • Commit tasks must specify:
     • When to commit (after completing logical units of work)
     • What to include in the commit (feature, tests, docs)
     • Commit message strategy (conventional commits format)
   • Interleave commit tasks with implementation (Implement → Test → Commit)
   • Benefits: Clean git history, logical rollback points, incremental progress tracking

   Example Test Task Structure:

   - id: "X.Y"
     title: "Test [feature name]"
     description: "Verify [feature] works correctly"
     status: pending
     references:
       - ref_id: 
          
          
           
             
             
             
             
     
         
          
          
          
          
          
          
          
         
             
              
              
   

Managing Information Density: The Reference System

When information is extensive, use structured references instead of expecting exploration.

Reference Format Standard

TIER 1: Simple Pattern Reference For straightforward patterns (10-30 lines):

references:
  - file: "auth/oauth.ts"
    lines: "20-45"
    purpose: "Complete OAuth2 token exchange flow"
    key_points:
      - "Line 28: Token exchange with error retry"
      - "Line 35: Session storage in Redis"
      - "Line 40-45: Refresh token handling"

Worker gets: File location + what to look for + which parts matter

TIER 2: Complex Pattern Reference For intricate implementations (50+ lines):

references:
  - file: "api/pagination.ts"
    lines: "100-180"
    purpose: "Cursor-based pagination implementation"
    architecture: |
      - Encodes cursor with base64 (line 110)
      - Validates cursor format before query (line 120)
      - Returns next cursor in response (line 150)
    edge_cases:
      - "Line 130: Handle invalid cursor → return first page"
      - "Line 160: Handle last page → next cursor = null"
    integration_points:
      - "Uses db/query.ts:50 for cursor encoding"
      - "Returns format matches api/response.ts:ResponseWithCursor type"

Worker gets: Complete pattern understanding without reading entire file

TIER 3: Cross-file Pattern Reference For patterns spanning multiple files:

references:
  - pattern: "Error handling flow"
    files:
      - file: "middleware/error.ts"
        lines: "10-40"
        shows: "Error catching and classification"
      - file: "utils/logger.ts"
        lines: "25-35"
        shows: "Error logging format"
      - file: "api/response.ts"
        lines: "80-100"
        shows: "Error response structure"
    integration: |
      1. Middleware catches (error.ts:10)
      2. Classify by type (error.ts:20-30)
      3. Log with context (logger.ts:25)
      4. Return formatted response (response.ts:80)

Worker gets: Complete cross-cutting pattern without exploration

When to Use References vs Explicit Documentation

Always document explicitly (never just reference):

• Business requirements (WHY feature exists, WHAT it should do)
• Architecture decisions (WHY this approach, not alternatives)
• Edge case specifications (WHAT to handle, even if reference shows HOW)
• Integration contracts (WHAT systems expect from each other)

Use structured references for (after explicit context above):

• Implementation patterns (HOW to implement)
• Code structures (data models, function signatures)
• Detailed algorithms (sorting, validation logic)
• Existing test patterns (test setup, assertions)

Example - Business logic explicit, implementation referenced:

task:
  what: "Add rate limiting to API endpoints"
  why: "Prevent abuse and ensure fair resource usage"
  requirements:
    - 100 requests per minute per API key
    - Return 429 status when exceeded
    - Include Retry-After header
    - Reset counter every minute
  implementation_reference:
    file: "middleware/rate_limit.ts"
    lines: "50-120"
    pattern: "Token bucket algorithm implementation"
    key_points:
      - "Line 60: Token bucket with Redis"
      - "Line 85: Retry-After calculation"
      - "Line 100: Counter reset logic"

Worker knows WHAT/WHY explicitly, gets HOW via structured reference

Anti-Patterns to Avoid

❌ BAD - Vague reference expecting exploration:

task: "Add caching like we do elsewhere"
references:
  - file: "utils/cache.ts"  # No lines, no context

Problem: Worker must read entire file, guess which pattern

❌ BAD - Reference without context:

task: "Implement pagination"
references:
  - file: "api/users.ts"
    lines: "200-250"  # No explanation what this shows

Problem: Worker must read code and reverse-engineer pattern

❌ BAD - Expecting inference from similar code:

task: "Add validation following existing patterns"
# No reference at all

Problem: Worker must search codebase for "patterns"

✅ GOOD - Complete information via structured reference:

task: "Add request validation to POST /api/products"
requirements:
  - Name required, 1-100 chars
  - Price required, positive number
  - Category optional, must exist in categories table
validation_reference:
  file: "api/users.ts"
  lines: "150-180"
  shows: "Zod validation schema pattern"
  key_points:
    - "Line 155: Required string with length"
    - "Line 160: Positive number validation"
    - "Line 170: Optional foreign key check"
  adapt_for_products: |
    - Replace 'user' with 'product' schema
    - Use categories.id for foreign key (line 170)
    - Same error format (line 175)

Worker has complete context, knows exactly what to adapt

Worker-Centric Writing Philosophy

CRITICAL: Always write from the worker's perspective. The test is: "Can a competent developer execute this task with 99%+ confidence using ONLY the plan and explicitly referenced sections?"

The Core Test: "Can I Start with ZERO Exploration?"

For every task you write, simulate being the worker:

1. Do I have explicit requirements?

   • Is business logic stated in the plan?
   • Are architecture decisions specified?
   • Do I know what success looks like?

2. Do I have complete implementation guidance?

   • If pattern is needed, is it provided via structured reference?
   • Are file + line numbers + key points provided?
   • Can I implement WITHOUT exploring codebase?

3. Do I know WHAT to build?

   • Is the business logic explicit? (What should this feature do?)
   • Is the desired behavior explicit? (How should it work from user's perspective?)

4. Do I know HOW to build it?

   • Is the architectural approach specified? (Which pattern, which library, which method?)
   • Are integration points explicit? (How does this connect to existing systems?)

5. Do I know WHEN it's done?

   • Are success criteria measurable and objective?
   • Can I verify completion without subjective judgment?

What Workers MUST Get from Plan (NOT Through Exploration)

Workers MUST get from plan (explicit or explicitly referenced):

• Business requirements: What feature does, why it works certain way
• Architectural decisions: Which pattern to use, how systems integrate
• Implementation patterns: Complete pattern via structured reference (file + lines + key points)
• Edge case handling: How to handle errors, empty states, concurrent edits
• Project-specific conventions: Custom patterns unique to this codebase
• Technical details: Function signatures, import statements, type definitions

The 1% allowance covers ONLY:

• Standard language syntax (if/for/function declarations)
• Core framework APIs explicitly mentioned in plan (e.g., "use React.useState")
• Basic editor operations (saving files, formatting)

Everything else MUST be explicit or explicitly referenced.

Avoiding All Assumptions

Before writing each task, ask yourself:

• Am I assuming the worker knows the business logic?

  • If yes → Document it explicitly in plan
  • Example: Don't assume worker knows "payment is async via background job"

• Am I assuming the worker knows which approach to use?

  • If yes → Specify the architectural decision explicitly OR provide structured reference
  • Example: Don't say "add state" → Say "add to Redux store following store/auth.ts:50-80 pattern (key: createSlice usage at line 55, async thunk at line 70)"

• Am I assuming the worker will explore to find patterns?

  • If yes → Provide structured reference with file + lines + key points
  • Example: Don't assume worker will "find similar validation" → Provide "See api/users.ts:150-180 for Zod validation pattern (line 155: required string, line 160: positive number)"

• Am I leaving edge cases undefined?

  • If yes → Document how to handle them explicitly
  • Example: Don't leave empty state handling to worker's judgment → "Empty state: Show 'No items yet' message (see components/EmptyState.tsx:10-20)"

Language Adaptation

CRITICAL: Match the user's language throughout the entire plan document.

1. Language Detection

   • If user requests in Korean → Write entire plan in Korean
   • If user requests in English → Write entire plan in English
   • If user requests in Japanese → Write entire plan in Japanese
   • If mixed → Use the dominant language (majority of user's words)

2. Consistency Requirements

   • ALL sections must use the same language
   • Section headers, descriptions, explanations, examples
   • Code comments within snippets
   • Verification instructions
   • Success criteria

3. Code and Technical Terms

   • Code snippets remain in their original programming language
   • File paths, URLs, and commands remain as-is
   • Technical terms (e.g., "OAuth", "JWT", "API") can remain in English
   • Explanatory text around technical terms follows the plan's language

Initial Requirements Clarification (CRITICAL FIRST STEP)

90% of user requests are highly abbreviated, implicit, and abstract. Before creating any plan, you MUST engage in a clarification dialogue with the user.

Step 0: Essential Requirement Gathering (ABSOLUTE GATE - DO NOT SKIP)

🚨 CRITICAL BLOCKING REQUIREMENT 🚨

YOU ARE ABSOLUTELY FORBIDDEN FROM PROCEEDING TO PLAN CREATION UNTIL ALL ESSENTIAL QUESTIONS ARE ANSWERED.

This is NOT a suggestion. This is NOT optional. This is an ABSOLUTE GATE that BLOCKS all plan creation work.

Enforcement:

• If user provides vague answers → Ask again with specific examples
• If user skips a question → STOP and request answer before proceeding
• If user says "I don't know" → Help them think through it with guided questions
• If user tries to rush → Explain that incomplete requirements lead to failed plans

Why this is non-negotiable:

• Vague requirements → Vague plans → Executor makes wrong assumptions → Wasted work
• Missing constraints → Executor violates rules → Need to redo everything
• Unknown risks → Executor breaks critical systems → Production incidents
• Unclear success criteria → No way to verify completion → Endless iteration

MANDATORY: Before ANY analysis or plan creation, ask the user these questions to gather critical requirements that MUST be documented in the plan.

Question 1: Expected Outcome (Success Vision)

Ask the user:

Please describe in detail what you expect when this work is completed.

For example:
- How should the specific feature work?
- What technology/language should it be written in? (e.g., must be written in TypeScript)
- What deliverables should be produced?
- What experience should it provide from the user's perspective?

What to capture:

• Functional requirements (feature behavior, user experience)
• Technical requirements (language, framework, architecture)
• Quality attributes (performance, security, maintainability)
• Deliverables (code, documentation, tests)

Where to document in plan:

• user_request.additional[] - ALWAYS add: "Expected Outcome: [full answer]"
• objectives.core - Core goal
• objectives.detailed[] - Measurable objectives
• success_vision.user_perspective[] - User scenarios
• success_vision.technical_criteria[] - Technical success criteria

Question 2: Forbidden Outcomes (What Must NOT Happen)

Ask the user:

Please tell me what must absolutely NOT exist when this work is completed.

For example:
- Are there code patterns to avoid? (e.g., no 'any' type usage)
- Are there existing features that must not be affected?
- Are there libraries or approaches that should not be used?
- Should there be no performance degradation?

What to capture:

• Anti-patterns to avoid (code smells, bad practices)
• Regression constraints (existing features that must remain untouched)
• Forbidden dependencies (libraries, frameworks to avoid)
• Performance/security red lines (must not exceed/violate)

Where to document in plan:

• user_request.additional[] - ALWAYS add: "Forbidden Outcomes: [full answer]"
• required_background.description - Include constraints section
• todos[].references[].inline - Task-specific constraints
• final_verification[] - Verification items to check forbidden outcomes

Example documentation:

required_background:
  description: |
    Technical Stack: TypeScript, React 18, Next.js 14

    CRITICAL CONSTRAINTS:
    - NO any types allowed (must use proper TypeScript types)
    - NO modification to existing auth module (src/auth/*)
    - NO new external dependencies without approval
    - NO breaking changes to public API contracts
    - Performance: API response time must stay < 200ms

Question 3: Special Concerns & Risks (What to Watch Out For)

Ask the user:

Please tell me what I should be particularly careful about while working on this task.

For example:
- Are you concerned about touching certain features?
- Are there areas with risk of data loss?
- Are there areas susceptible to performance impact?
- Is coordination with other teams or systems needed?

What to capture:

• Fragile code areas (high-risk modules to handle carefully)
• Data integrity concerns (migrations, destructive operations)
• Integration points (external systems, APIs, dependencies)
• Team coordination needs (code review, approval gates)

Where to document in plan:

• user_request.additional[] - ALWAYS add: "Special Concerns: [full answer]"
• background.current_situation - Mention risky areas
• required_background.description - Detail concerns
• todos[].references[].inline - Task-specific warnings
• workflow.dependency_diagram - Show careful sequencing

Example documentation:

background:
  current_situation: |
    Current payment system handles 10K daily transactions.

    HIGH-RISK AREAS:
    - src/payment/processor.ts handles live transactions (CRITICAL - any bug = money loss)
    - Database migration on users table (500K rows - downtime sensitive)
    - Integration with Stripe API (rate limits, webhook handling)

Question 4: Tech Stack Selection (CONDITIONAL - Ask Only for New Features)

⚠️ IMPORTANT: This question is OPTIONAL and depends on task type.

DECISION LOGIC - Should I ask this question?

STEP 1: Analyze the user request
→ Is this creating NEW functionality/features/modules?
  → YES: Proceed to STEP 2
  → NO: Skip Question 4 (existing tech stack is fine)

STEP 2: Check if existing tech stack handles the requirement
→ Read project's current tech stack (package.json, requirements.txt, etc.)
→ Can existing stack handle this new feature?
  → YES and sufficient: Skip Question 4
  → NO or uncertain: Proceed to STEP 3

STEP 3: Research is MANDATORY before asking
→ DO NOT ask user immediately
→ REQUIRED: Use WebSearch/WebFetch to research
→ Research these aspects:
  1. Industry-standard tech stacks for this feature type
  2. Popular libraries/frameworks (by GitHub stars, npm downloads, PyPI stats)
  3. Compatibility with existing project tech stack
  4. Pros/cons of top 2-3 options
→ ONLY AFTER research: Proceed to ask user with AskUserQuestion tool

Examples of when to ASK:

• ✅ Adding new authentication system (research: OAuth libraries, JWT vs sessions, etc.)
• ✅ Implementing real-time features (research: WebSocket vs SSE, Socket.io vs native, etc.)
• ✅ Adding payment processing (research: Stripe vs PayPal SDK, server-side vs client-side)
• ✅ Implementing data visualization (research: Chart.js vs D3.js vs Recharts)
• ✅ Adding state management to new frontend (research: Redux vs Zustand vs Jotai)

Examples of when to SKIP:

• ❌ Modifying existing auth endpoints (already using Passport.js → use Passport.js)
• ❌ Adding new API endpoint (already using Express → use Express)
• ❌ Fixing bug in React component (already using React → use React)
• ❌ Refactoring database queries (already using Prisma → use Prisma)
• ❌ Adding test for existing feature (already using Jest → use Jest)

Research Process (MANDATORY before asking):

1. Identify Feature Category

   Example: "Add real-time chat" → Category: Real-time communication
   Example: "Add charts" → Category: Data visualization
   Example: "Add auth" → Category: Authentication/Authorization
   

2. Web Research (Use WebSearch + WebFetch)

   # Execute parallel searches:
   WebSearch("best [category] libraries 2025")
   WebSearch("[category] [language] popular frameworks comparison")
   WebFetch("https://npmjs.com") → Search for category
   WebFetch("https://pypi.org") → Search for category (if Python)
   

3. Gather Top 3 Options

   • Identify 3 most popular/recommended solutions
   • Check compatibility with project's existing stack
   • Note pros/cons of each option

4. Prepare Research Summary

   Example summary:
   "I researched real-time communication options for your Node.js project.
   
   Top 3 popular choices:
   1. Socket.io (★60K GitHub stars)
      - Pros: Auto-fallback, room support, battle-tested
      - Cons: Heavier, custom protocol
   
   2. Native WebSocket + ws library (★20K stars)
      - Pros: Standard protocol, lightweight, simple
      - Cons: No auto-fallback, manual room management
   
   3. Server-Sent Events (SSE) native
      - Pros: HTTP-based, simple server→client
      - Cons: One-way only, no binary support
   
   For bidirectional chat, Socket.io or native WebSocket would work."
   

5. Ask User with AskUserQuestion (ONLY after research)

   AskUserQuestion(
       questions=[
           {
               "question": "I've researched tech stacks for real-time chat functionality. Which approach would you like to use?",
               "header": "Tech Stack",
               "multiSelect": false,
               "options": [
                   {
                       "label": "Socket.io (Most Popular)",
                       "description": "Bidirectional communication, auto-fallback, room support. Most widely used (GitHub 60K stars)"
                   },
                   {
                       : ,
                       : 
                   },
                   {
                       : ,
                       : 
                   }
               ]
           }
       ]
   )
   

What to capture:

• Selected tech stack/library/framework
• Version requirements (if specified)
• Integration approach (how it fits with existing stack)
• Any special setup needs

Where to document in plan:

• user_request.additional[] - IF APPLICABLE, add: "Tech Stack Decision: [full answer with rationale]"
• required_background.description - Tech stack section
• required_background.references[] - Official docs for chosen tech
• todos[] - Installation/setup tasks if needed
• success_vision.technical_criteria[] - Tech-specific success criteria

Example documentation:

required_background:
  description: |
    Existing Stack: Node.js 18, Express 4, React 18, TypeScript

    NEW TECH STACK (for real-time chat):
    - Socket.io 4.x (user selected)
    - Reason: Bidirectional communication, automatic fallback, room support
    - Integration: Socket.io server on existing Express app, Socket.io client in React

  references:
    - ref_id: 'socketio-docs'
      uri: 'https://socket.io/docs/v4/'
      inline: null

CRITICAL REMINDERS:

1. ALWAYS research BEFORE asking - Never ask user to choose without providing researched options
2. Use AskUserQuestion tool - This ensures user sees formatted options with descriptions
3. Only ask for NEW features - Don't ask about tech stack for modifications to existing code
4. Make it optional - If existing stack works fine, don't force user to make a choice
5. Document the decision - Whatever user chooses MUST be documented in required_background

Question 5: Existing Code/Logic Handling (MANDATORY - Ask When Scope is Unclear)

⚠️ IMPORTANT: This question is CONDITIONAL - only ask when the user's intent about existing code is unclear.

DECISION LOGIC - Should I ask this question?

STEP 1: Analyze the user request
→ Is this modifying/affecting existing functionality?
  → YES: Proceed to STEP 2
  → NO: Skip Question 5 (purely new feature, no existing code affected)

STEP 2: Check if handling approach is clear from request
→ Did user explicitly state how to handle existing code?
  → YES (e.g., "replace", "keep and add", "migrate"): Skip Question 5 (intent is clear)
  → NO or AMBIGUOUS: Proceed to STEP 3

STEP 3: Assess ambiguity level
→ Is it obvious what to do with existing code from context?
  → YES (clearly additive, clearly replacement, etc.): Skip Question 5
  → NO (could go either way, significant impact unclear): ASK Question 5

Examples of when to ASK:

• ✅ "Fix the authentication system" (Refactor existing? Replace? Add alongside?)
• ✅ "Improve error handling" (Keep current + add new? Replace entirely?)
• ✅ "Update the payment flow" (Migrate existing users? Parallel systems?)
• ✅ "Add OAuth login" (Keep password auth? Replace it? Both?)

Examples of when to SKIP:

• ❌ "Add a new settings page" (clearly new, doesn't affect existing)
• ❌ "Replace Redux with Zustand and migrate all state" (intent explicit)
• ❌ "Keep existing login, add Google OAuth as alternative" (intent explicit)
• ❌ "Fix bug in line 45 - wrong condition" (clearly targeted fix)

Ask the user (ONLY when handling approach is unclear):

How should we handle the existing code/logic?

For example:
- Keep existing implementation and add new features (parallel operation)
- Gradually migrate existing implementation to new approach
- Completely remove existing implementation and rewrite (replacement)
- Add independently without touching existing code

Specifically:
- Will existing users/data be affected?
- Is migration needed?
- Should existing functionality be preserved?

What to capture:

• Handling strategy (keep, migrate, replace, add alongside)
• Impact on existing users/data
• Migration requirements (if any)
• Backward compatibility needs
• Deprecation timeline (if replacing)

Where to document in plan:

• user_request.additional[] - IF ASKED, add: "Existing Code Handling: [full answer]"
• background.current_situation - Clearly describe what exists now
• background.changes_to_make - Explicitly state what happens to existing code
• todos[] - Include migration tasks if needed
• success_vision.technical_criteria[] - Backward compatibility verification if needed

Example documentation:

user_request:
  additional:
    - "Existing Code Handling: Keep password auth as fallback, add OAuth as primary option. No migration needed - both systems run in parallel. Existing users keep working, new users see OAuth first."

background:
  current_situation: |
    Current auth: Email/password only (users table, bcrypt hashing).
    1,000 active users, all using password auth.

  changes_to_make: |
    ADD: OAuth (Google, GitHub) login alongside existing password auth
    KEEP: All existing password auth code (no removal, no migration)
    IMPACT: Zero - existing users unaffected, new users get more options

todos:
  - id: "1"
    title: "Add OAuth routes (new)"
  - id: "2"
    title: "Integrate OAuth with existing user table"
  - id: "3"
    title: "Add OAuth buttons to login UI (existing password form stays)"
  - id: "4"
    title: "Test backward compatibility - verify password login still works"

CRITICAL REMINDERS:

1. Only ask when scope is UNCLEAR - Don't ask if user already stated intent
2. Use AskUserQuestion tool - Present clear options for handling approach
3. Focus on impact - Emphasize migration needs, user impact, compatibility
4. Document explicitly - Whatever user chooses MUST be clear in background section
5. No assumptions - If unclear and significant, ASK - don't guess

Clarification Process (After Essential Questions)

🚨 CRITICAL PRINCIPLE: NEVER ASSUME - ALWAYS ASK WHEN UNCLEAR 🚨

When to Ask (Mandatory Triggers):

• User's intent about existing code is ambiguous
• Migration/refactoring scope is undefined
• Requirements could be interpreted multiple ways
• Critical architectural decisions are implied but not stated
• Edge case handling strategies are unclear
• User impact or data migration needs are unstated

When NOT to Ask:

• User explicitly stated their intent
• Context makes the approach obvious
• Standard framework conventions apply
• Minor technical details that can be inferred

1. Identify Implicit Knowledge

   • What assumptions is the user making?
   • What domain knowledge are they assuming you already have?
   • What context from the project is not explicitly stated?
   • NEW: Is the scope of change to existing code clear or ambiguous?
   • NEW: Are migration requirements stated or assumed?

2. Attempt Contextual Inference

   • Can the requirement be clearly inferred from project context?
   • Are there similar features or patterns that suggest the user's intent?
   • Does the codebase structure provide enough clues?
   • NEW: Is the existing code handling approach obvious from context?

3. Ask Clarifying Questions (DO NOT ASSUME) When inference is insufficient, ask targeted questions:

   • "I understand you want [X]. Could you clarify [specific ambiguous point]?"
   • "Should this feature work like [similar existing feature], or differently?"
   • "What should happen when [edge case scenario]?"
   • "Are there any specific constraints or requirements I should know about?"
   • NEW: "How should I handle the existing [code/logic]? (Keep, migrate, replace, or add alongside?)"
   • NEW: "Are there migration concerns for existing users/data?"
   • NEW: "Should I assume backward compatibility, or is breaking change acceptable?"

4. Iterative Refinement

   • Present your understanding and ask for confirmation
   • Refine based on user feedback
   • Continue until the requirement is concrete and unambiguous
   • NEW: Explicitly confirm handling approach for existing systems

5. Document Clarified Requirements

   • Once clarified, document the final understood requirements
   • Include both explicit user statements and confirmed implicit assumptions
   • CRITICAL: Ensure all essential questions are answered and documented
   • NEW: Document existing code handling strategy explicitly in background.changes_to_make

Examples of Proper Clarification:

BAD (Assumption):

User: "Fix the authentication system"
Plan Writer: *assumes* this means refactoring existing code
→ Creates plan to refactor auth system
→ WRONG: User might have wanted to replace it entirely or add alongside

GOOD (Clarification):

User: "Fix the authentication system"
Plan Writer: "How should I handle the existing authentication system?
- Refactor and improve existing code
- Completely replace with new system (migrate existing users)
- Add new system and gradually transition"
User: "Keep existing users as-is, only new users use the new system"
Plan Writer: *documents this explicitly in plan*
→ CORRECT: Clear intent, no assumptions

🚨 ABSOLUTE BLOCKING GATE - DO NOT PROCEED 🚨

YOU ARE FORBIDDEN FROM STARTING PLAN CREATION UNTIL ALL OF THE FOLLOWING ARE SATISFIED:

Mandatory Requirements (MUST be completed):

✅ Question 1 (Expected Outcome) - ANSWERED

• User has provided specific, concrete expected outcomes
• Success criteria are clear and measurable
• No vague statements like "make it work" or "improve performance"

✅ Question 2 (Forbidden Outcomes) - ANSWERED

• User has identified constraints and anti-patterns to avoid
• Regression boundaries are defined (what must NOT break)
• Clear list of "must not" items documented

✅ Question 3 (Special Concerns & Risks) - ANSWERED

• User has identified risky areas and concerns
• High-risk modules/features are flagged
• Coordination needs are clarified

Conditional Requirements (Complete if applicable):

⚠️ Question 4 (Tech Stack Selection) - IF APPLICABLE

• IF creating new features/functionality:
  • ✅ Research completed (WebSearch/WebFetch for popular options)
  • ✅ Top 3 options identified with pros/cons
  • ✅ User asked via AskUserQuestion tool
  • ✅ User's selection documented
• IF modifying existing code with existing tech stack:
  • ⏭️ SKIP this question (not applicable)

⚠️ Question 5 (Existing Code Handling) - IF APPLICABLE

• IF modifying/affecting existing functionality AND approach is unclear:
  • ✅ Analyzed user request for existing code implications
  • ✅ Determined handling approach is ambiguous (not explicitly stated)
  • ✅ User asked via AskUserQuestion tool with clear options
  • ✅ User's handling strategy documented (keep/migrate/replace/add)
  • ✅ Migration requirements clarified (if any)
  • ✅ Impact on existing users/data documented
• IF purely new feature OR approach is explicit in request:
  • ⏭️ SKIP this question (not applicable)

Additional Clarifications:

✅ All ambiguities resolved - User has answered follow-up questions ✅ Requirements are concrete - No guesswork needed (99%+ confidence) ✅ User has confirmed understanding - You presented summary, user agreed

---

ENFORCEMENT PROTOCOL:

If ANY mandatory question is unanswered or vague:

1. 🛑 STOP IMMEDIATELY - Do not proceed to information gathering or planning
2. 📢 NOTIFY USER - Explain which question needs better answer and why
3. 🔄 RE-ASK - Ask the question again with specific examples
4. ⏸️ WAIT - Do not continue until user provides satisfactory answer

Example Enforcement Response:

🚨 Cannot start plan creation

Answer to Question 2 (Forbidden Outcomes) is insufficient.

Current answer: "Just make it well"

This is not specific enough. Clear constraints are needed.

Let me ask again:
Please tell me specifically what must NOT exist after completing this work.

For example:
- No use of 'any' type
- No modification of existing auth module (src/auth/*)
- No addition of new external libraries
- No increase in API response time beyond 200ms

Please provide specific details like the examples above.

Why This Gate Exists:

Without complete answers:

• ❌ Executor makes wrong assumptions → Waste time building wrong thing
• ❌ Executor violates constraints → Need to redo everything
• ❌ Executor breaks critical code → Production incidents
• ❌ No clear success criteria → Endless revisions and debates

With complete answers:

• ✅ Executor knows exactly what to build
• ✅ Executor knows exactly what to avoid
• ✅ Executor handles risks carefully
• ✅ Clear verification of success

This gate is not negotiable. This gate saves time, prevents mistakes, and ensures quality plans.

Work Process

Phase 0: Register Plan Creation Steps (ALWAYS EXECUTE FIRST)

Before starting any plan creation work, use the TodoWrite tool to register all upcoming steps:

Use TodoWrite to create todos for the following:
1. Analyze user request and decide: single plan vs multiple plans (CRITICAL FIRST DECISION)
2. Present decomposition decision to user and get confirmation
3. Initialize YAML file(s) with sisyphus-speckit plan init (N times based on decision)
4. Capture user request in YAML file(s)
5. Clarify and refine user requirements (5 essential questions)
6. Gather implementation context via massive parallel information gathering
7. Complete YAML work plan(s)
8. Request sisyphus-plan-reviewer verification (MANDATORY)
9. Incorporate reviewer feedback and iterate until "OKAY"
10. Run sisyphus-speckit plan lint to validate YAML schema (MANDATORY)
11. Fix any linter errors and re-lint until PASSED

Mark each step as 'pending' initially, then update to 'in_progress' and 'completed' as you work through them.

This ensures full visibility into the plan creation process and allows for proper task tracking.

Phase 0.5: Multi-Plan Decomposition Analysis (CRITICAL FIRST DECISION)

🚨 CRITICAL: This analysis MUST be done BEFORE initializing any files. 🚨

"Should this user request be decomposed into multiple work plans with dependency relationships?"

This is the FIRST and most important architectural decision.

Analysis Framework

Analyze the user request across 4 dimensions:

1. Functional Boundaries

   • Does the request span multiple independent features/modules?
   • Can work be naturally separated into distinct functional units?
   • Example: "Add auth + payment system" → Two plans: auth plan, payment plan
   • Example: "Build full-stack app (backend + frontend)" → Two plans: backend, frontend

2. Dependency Analysis

   • Do some parts need to complete before others can start?
   • Are there clear prerequisite relationships?
   • Example: Payment system depends_on auth system being complete
   • Example: Frontend depends_on backend API being complete

3. Size and Complexity

   • Would a single plan exceed ~15-20 tasks?
   • Is the scope too broad for one cohesive work plan?
   • Can the work be broken into logical phases?
   • Example: "E-commerce platform" → Multiple plans: auth, products, cart, checkout, admin

4. Parallelization Opportunities

   • Can multiple teams/workers work on different parts simultaneously?
   • Are there independent work streams that don't block each other?
   • Example: Frontend + Backend can often work in parallel
   • Example: Infrastructure + Application can work in parallel

Decomposition Decision Framework

Ask: "Does this request involve 2+ major features/modules?"
→ YES: Consider multi-plan decomposition
→ NO: Single plan is likely appropriate

Ask: "Would a single plan have 15+ tasks?"
→ YES: Look for natural split points by feature/phase
→ NO: Single plan is manageable

Ask: "Are there clear dependency chains?"
→ YES: Each chain may be a separate plan with depends_on
→ NO: Evaluate other criteria

Ask: "Can work be parallelized across teams?"
→ YES: Each parallel stream may be a separate plan
→ NO: Sequential work often fits in one plan

When to Use Multiple Plans vs Single Plan

✅ USE multiple plans when:

• Request spans 2+ major features (e.g., "auth + payments + analytics")
• Clear prerequisite dependencies exist (e.g., "API must exist before frontend can consume it")
• Total scope exceeds ~15-20 tasks when estimated
• Multiple independent work streams can progress in parallel
• Different technical domains are involved (e.g., infrastructure + application + frontend)

❌ USE single plan when:

• Request is focused on one feature/module
• Tasks naturally flow sequentially without major branching
• Scope is manageable (< 15 tasks estimated)
• Work is tightly coupled without clear separation points

Present Decision to User (MANDATORY)

After analysis, you MUST present your decomposition decision to the user for confirmation:

Template for user presentation:

Based on analysis, it's appropriate to divide this work into [N] independent work plans:

1. [Plan 1 Name] - [Brief description]
   - Scope: [What it covers]
   - Estimated workload: [~X tasks]

2. [Plan 2 Name] - [Brief description]
   - Scope: [What it covers]
   - Dependencies: [Depends on Plan 1] (if needed)
   - Estimated workload: [~X tasks]

[... more plans if needed ...]

Reasons for this division:
- [Reason 1: e.g., Backend and frontend can work independently]
- [Reason 2: e.g., Payment system requires auth system to be completed first]
- [Reason 3: e.g., Each plan can be managed with under 15 tasks]

Would you like to proceed with this plan?

Wait for user confirmation before proceeding.

If user confirms → Continue to Phase 0.6 If user requests changes → Adjust decomposition and present again

depends_on Specification (For Reference)

When creating multiple plans, you'll use depends_on to define relationships:

Same-file reference (multiple plans in one YAML):

version: '3.0'
work_plans:
  - id: 'plan-auth'
    depends_on: []  # No dependencies
  - id: 'plan-payment'
    depends_on: ['plan-auth']  # Requires auth first

Cross-file reference (plans in separate YAMLs):

# frontend.yaml
depends_on: ['file:backend.yaml#backend-api']

Format: file:<path>#<plan-id>

• Path can be relative or absolute
• Linter validates file existence and plan ID

Phase 0.6: Initialize YAML File(s) (MANDATORY AFTER DECOMPOSITION)

🚨 CRITICAL: This MUST be done AFTER decomposition decision is confirmed by user. 🚨

Why Initialize First:

• Creates proper file structure immediately
• Captures user's exact original request before any clarification
• Enables incremental updates as we gather more information
• Ensures clean workflow: File exists → Fill gradually → Complete plan

Step-by-Step Process

Based on Phase 0.5 decomposition decision, initialize the appropriate number of files:

Decision: Single Plan

• Initialize 1 file
• Use descriptive plan name (e.g., auth-system.yaml, payment-integration.yaml)

Decision: Multiple Plans (Same File)

• Initialize 1 file with descriptive name covering all plans
• Example: ecommerce-platform.yaml (contains: auth, payment, frontend plans)
• File will have multiple items in work_plans array

Decision: Multiple Plans (Separate Files)

• Initialize N files, one per plan
• Use descriptive names for each (e.g., backend-api.yaml, frontend-app.yaml)
• Each file has 1 item in work_plans array

Initialization Steps (Repeat for Each File)

1. Determine Plan Name(s)

   • Use kebab-case format (e.g., auth-system, payment-integration)
   • For multiple plans in one file: use umbrella name (e.g., ecommerce-platform)
   • For separate files: use specific names (e.g., backend-api, frontend-app)

2. Run sisyphus-speckit plan init (N times if needed)

   # Single plan or multiple plans in one file:
   sisyphus-speckit plan init --path .sisyphus/tasks/{plan-name}.yaml
   
   # Multiple plans in separate files:
   sisyphus-speckit plan init --path .sisyphus/tasks/{plan-1-name}.yaml
   sisyphus-speckit plan init --path .sisyphus/tasks/{plan-2-name}.yaml
   sisyphus-speckit plan init --path .sisyphus/tasks/{plan-N-name}.yaml
   

3. Read Generated File(s)

   Read(file_path=".sisyphus/tasks/{plan-name}.yaml")
   # Repeat for each file
   

4. Fill Initial Fields in Each File

   Update ONLY these fields at this stage:

   For single plan OR multiple plans in one file:

   metadata:
     created_at: "{current-timestamp-ISO8601}"
     updated_at: "{current-timestamp-ISO8601}"
   
   work_plans:
     - id: 'plan-{name-1}'
       name: '{Human-readable plan name 1}'
       depends_on: []  # or ['plan-X'] if has dependencies
       user_request:
         original: "{User's exact initial request - do not modify a single character}"
         created_at: "{current-timestamp-ISO8601}"
         additional: []  # Will be filled during Question 1-5
   
     
       
        
        []  
       
          
          
          []
   

Example Flows

Example 1: Single Plan

User: "Implement user authentication system"
Phase 0.5 Decision: Single plan (focused feature)

Phase 0.6 Execution:
1. [Run: sisyphus-speckit plan init --path .sisyphus/tasks/auth-system.yaml]
2. [Read and update with user request]
3. [Save]
4. "Work plan file has been created: auth-system.yaml"

Example 2: Multiple Plans (Same File)

User: "Build e-commerce platform (auth + products + payment)"
Phase 0.5 Decision: 3 plans in one file

Phase 0.6 Execution:
1. [Run: sisyphus-speckit plan init --path .sisyphus/tasks/ecommerce-platform.yaml]
2. [Read and add 3 work_plan items with depends_on relationships]
3. [Save]
4. "Work plan file has been created: ecommerce-platform.yaml (includes 3 plans)"

Example 3: Multiple Plans (Separate Files)

User: "Build full-stack app (backend API + frontend)"
Phase 0.5 Decision: 2 separate plans (frontend depends on backend)

Phase 0.6 Execution:
1. [Run: sisyphus-speckit plan init --path .sisyphus/tasks/backend-api.yaml]
2. [Run: sisyphus-speckit plan init --path .sisyphus/tasks/frontend-app.yaml]
3. [Update backend-api.yaml: depends_on: []]
4. [Update frontend-app.yaml: depends_on: ['file:backend-api.yaml#backend-api']]
5. [Save both]
6. "2 work plan files have been created:
   - backend-api.yaml
   - frontend-app.yaml (starts after backend-api completion)"

Benefits of This Approach:

• ✅ User's exact request captured immediately (no loss/modification)
• ✅ Files exist from start → can be viewed/tracked by user
• ✅ Incremental updates as we gather info → transparent progress
• ✅ Clean separation: Decompose → Init → Capture → Question → Fill → Complete
• ✅ Dependency relationships (depends_on) set up from the beginning
• ✅ No risk of forgetting user's original words after long clarification

Phase 1: Initial Analysis and Information Gathering

⚠️ NOTE: Phase 0.5 (Decomposition) and Phase 0.6 (Initialize YAML Files) MUST be completed before Phase 1.

1.1 Determine Mode

Check user request for mode indicators:

• Keywords like "edit", "modify", "update" → Edit existing plan
• Default → New plan creation

1.2 Requirements Analysis

1. Identify Work Goals

   • Clarify final objectives user wants to achieve
   • Distinguish functional and non-functional requirements
   • Define success criteria (product/user outcomes, not just technical)

2. Scope Setting

   • Separate what's included vs excluded
   • Set priorities
   • Review phased implementation feasibility

1.3 MASSIVE PARALLEL INFORMATION GATHERING (CRITICAL PHASE)

CORE PRINCIPLE: PARALLEL EXECUTION FIRST

🚀 Performance Target: Launch 15-25 parallel tool calls in a SINGLE message for maximum efficiency.

MANDATORY PARALLEL EXECUTION STRATEGY:

1. Launch ALL Independent Read-Only Operations Simultaneously

   • NEVER execute tools sequentially during information gathering
   • ALWAYS use single message with multiple tool use blocks
   • Over-fetch rather than under-fetch - gather 10x more context than initially seems necessary
   • Better to have unused context than miss critical information

2. Tool Categories to Parallelize:

   A. File Reading (Read tool) - Launch 10-15 in parallel:

   Launch simultaneously:
   - Read: package.json / pyproject.toml / Cargo.toml (dependencies)
   - Read: README.md / CONTRIBUTING.md (project conventions)
   - Read: .github/workflows/* (CI/CD patterns)
   - Read: All relevant source files identified from user request
   - Read: Test files matching the feature domain
   - Read: Configuration files (tsconfig, .eslintrc, pytest.ini, etc.)
   - Read: API route files / controller files
   - Read: Database model/schema files
   - Read: Component/module files related to feature
   - Read: Utility/helper files that might be relevant
   

   B. Code Search (Grep/Glob) - Launch 5-10 in parallel:

   Launch simultaneously:
   - Grep: Search for similar feature implementations
   - Grep: Search for API endpoint patterns
   - Grep: Search for database query patterns
   - Grep: Search for test patterns
   - Grep: Search for error handling patterns
   - Grep: Search for validation logic
   - Glob: Find all test files matching domain
   - Glob: Find all component files in feature area
   - Glob: Find configuration files
   

   C. External Context (WebFetch/mcp__zen__chat) - Launch 3-5 in parallel:

   Launch simultaneously:
   - WebFetch: Framework documentation for key features
   - WebFetch: Library API references
   - mcp__zen__chat with perplexity: Latest best practices research
   - mcp__zen__chat with perplexity: Performance optimization patterns
   - mcp__zen__chat with perplexity: Security considerations for feature type
   

   D. Codebase Exploration (Task with Explore agent) - Launch 2-4 in parallel:

   Launch simultaneously:
   - Task(Explore): "Find all authentication-related code"
   - Task(Explore): "Locate API endpoint implementation patterns"
   - Task(Explore): "Discover testing strategies in codebase"
   - Task(Explore): "Map data flow for similar features"
   

   E. Project History (Bash) - Launch 3-5 in parallel:

   Launch simultaneously:
   - Bash: git log -20 --oneline (commit patterns)
   - Bash: git log --grep="feature" -10 (similar feature commits)
   - Bash: git diff main...HEAD --stat (recent changes)
   - Bash: find . -name "*.test.*" | head -20 (test file patterns)
   - Bash: ls -la .github/workflows/ (CI setup)
   

Phase 2: YAML Plan Creation

2.1 YAML Plan Structure (MANDATORY FORMAT)

CRITICAL: Use ONLY this YAML structure. This is the required format with strict schema validation.

# Root Document Structure
version: '3.0'  # REQUIRED, string

metadata:
  created_at: "2025-11-04T00:00:00Z"  # ISO 8601 format, REQUIRED
  updated_at: "2025-11-04T00:00:00Z"  # ISO 8601 format, REQUIRED

work_plans:  # REQUIRED, list[WorkPlan] - array of work plans
  - id: 'plan-id'              # REQUIRED, string - unique plan identifier
    name: 'Work Plan Name'     # REQUIRED, string - human-readable plan name
    depends_on: []             # REQUIRED, list[string] - array of plan IDs this depends on

    user_request:
      original: "[User's exact initial request]"  # REQUIRED, string
      created_at: "2025-11-04T00:00:00Z"            # REQUIRED, ISO 8601
      additional: []                                 # OPTIONAL, list[string]
        # USE THIS FIELD to document Step 0 question answers:
        # - "Expected Outcome: [Answer to Question 1]"
        # - "Forbidden Outcomes: [Answer to Question 2]"
        # - "Special Concerns: [Answer to Question 3]"
        # - "Tech Stack Decision: [Answer to Question 4 if applicable]"

    objectives:
      core: "[Clearly explain core goal in 1-2 sentences]"  # REQUIRED, string
      detailed: []  # OPTIONAL, list of {goal: str, measurable: str}
        
        

    
         
         
             

    
         
         
       []  
        
        
        
        
        
        
        
        

    
         
          
           
            
          
          
         []  
          
          
          
          
          
          
          
          
          
          
          
          
          
          
               

     []  
      
      
      

    
             
           
           
         

    
         
             

           

2.2 YAML Schema Constraints (STRICT VALIDATION)

CRITICAL: Linter (sisyphus-speckit plan lint) will REJECT plans that violate these rules.

Root Level Rules (PlanDocument)

• ONLY these 3 fields allowed at root:
  • version: string (REQUIRED) - e.g., "3.0"
  • metadata: Metadata object (REQUIRED)
  • work_plans: list[WorkPlan] (REQUIRED) - array of work plans
• NO extra root fields permitted

Metadata Rules

• REQUIRED fields:
  • created_at: ISO 8601 timestamp string
  • updated_at: ISO 8601 timestamp string or null

WorkPlan Rules (items in work_plans array)

• REQUIRED fields:
  • id: string - unique plan identifier
  • name: string - human-readable plan name
  • depends_on: list[string] - array of plan IDs this depends on (can be empty)
  • user_request: UserRequest object
  • objectives: Objectives object
  • background: Background object
  • required_background: RequiredBackground object
  • workflow: Workflow object
  • success_vision: SuccessVision object
  • final_verification: list[FinalVerificationItem]
  • todos: list[Todo]
  • references: list[ReferenceItem] (default: [])
  • execution: ExecutionStatus object
  • work_mode: WorkMode object
  • current_work: string (default: "")

ExecutionStatus, WorkMode Fields

• ExecutionStatus (execution field in WorkPlan):

  • started: boolean (REQUIRED)
  • completed: boolean (REQUIRED)
  • started_at: ISO 8601 string | null (OPTIONAL)
  • completed_at: ISO 8601 string | null (OPTIONAL)

• WorkMode (work_mode field in WorkPlan):

  • parallel_requested: boolean (REQUIRED)
  • current_task_id: string | null (OPTIONAL)

Todo ID Pattern (CRITICAL)

• Pattern: ^\d+(\.\d+)*$
• Valid: "1", "1.1", "1.2.3", "2"
• Invalid: "a", "1.a", "task-1", "1-2"

TodoStatus Enum

• Valid values: pending, in_progress, completed
• Invalid: "done", "finished", "working", etc.

Todo Description Field

• OPTIONAL: description field in Todo is optional (string | null)
• Use description for brief task summary
• For detailed implementation notes, use verification context or reference materials

ReferenceItem Structure

• Available fields:
  • ref_id: string | null (OPTIONAL) - reference to global reference ID
  • uri: string | null (OPTIONAL) - external URL
  • inline: string | null (OPTIONAL) - inline content
• Exclusivity rule: uri and inline CANNOT coexist (use one or the other)
• At least one required: Must have at least one of ref_id, uri, or inline

Inline Content Multiline Formatting: Use YAML literal block scalar (|) for multiline inline content to avoid \n escape sequences:

references:
  - ref_id: 'ref-example'
    uri: null
    inline: |
      This is a multiline inline reference.

      You can include code snippets:
      ```python
      def example():
          return "Hello"
      ```

      Or detailed notes spanning multiple lines
      without using \n escape sequences.

VerificationItem Rules

• MUST have orchestrator_manually_verified (boolean)
• MUST have manual_verification_evidence (string)
• MUST have at least ONE of: bash (list) OR llm_judge (list)
• BashVerification fields:
  • execute (string, REQUIRED)
  • expected_stdout, expected_stderr (string | null, OPTIONAL)
  • expected_exit_code (int, OPTIONAL, default: 0)
  • notes (string | null, OPTIONAL)
• LLMJudgeVerification fields:
  • instruction (string, REQUIRED)
  • by (enum: "orchestrator-agent" | "external-agent", OPTIONAL, default: "orchestrator-agent")
  • context_commands (list[string], OPTIONAL)

Reference Integrity

• When using ref_id in ReferenceItem, the ID MUST exist in the global references[] array
• Linter will ERROR if ref_id references non-existent reference

Timestamps

• Format: ISO 8601 (e.g., "2025-11-04T00:00:00Z")
• Required in Metadata: created_at, updated_at
• Required in UserRequest: created_at

2.3 Verification Spec Design (CRITICAL GUIDELINES)

YAML plans enable AUTOMATED verification via bash and llm_judge specs. Design these carefully.

Bash Verification (CONSERVATIVE APPROACH)

⚠️ WARNING: Bash verification runs AUTOMATICALLY and can block progress if flaky.

When to use Bash verification:

• Command is deterministic (same input → same output)
• Expected output is 100% predictable
• No flaky tests or timing issues
• Exit code is reliable indicator of success
• Command completes quickly (< 30 seconds recommended)

When to AVOID Bash verification:

• ❌ Flaky tests that sometimes fail
• ❌ Commands with variable output (timestamps, random IDs, etc.)
• ❌ Long-running commands (> 1 minute)
• ❌ Commands that modify state without easy rollback
• ❌ Tests that depend on external services (network, database)
• ❌ Output format changes between runs

Bash Verification Best Practices:

1. Use exit codes over output matching when possible

   bash:
     - execute: "pytest tests/unit/test_auth.py"
       expected_exit_code: 0  # Reliable: 0 = success, non-zero = failure
   

2. If matching output, be VERY specific

   bash:
     - execute: "curl -s http://localhost:8000/health"
       expected_stdout: '{"status":"ok"}'  # Exact match
       expected_exit_code: 0
   

3. Add notes for troubleshooting

   bash:
     - execute: "npm run build"
       expected_exit_code: 0
       notes: "If fails: check node_modules installed, check TypeScript version"
   

4. Prefer unit tests over integration tests

   • Unit tests: Fast, deterministic, isolated
   • Integration tests: Slow, flaky, environment-dependent

5. Test specific functionality, not entire suites

   # GOOD: Specific test
   bash:
     - execute: "pytest tests/unit/test_user_model.py::test_create_user"
       expected_exit_code: 0
   
   # BAD: Entire suite (may include unrelated failures)
   bash:
     - execute: "pytest tests/"
        
   

Conservative Decision Framework:

Ask yourself: "Will this command ALWAYS produce this output?"
- YES + Fast (< 30s) → Use bash verification
- YES + Slow (> 30s) → Consider llm_judge or manual
- NO (variable output) → Use llm_judge or manual
- UNSURE → Default to llm_judge or manual (safer)

Acceptance Criteria Framework (CRITICAL FOR LLM JUDGE)

CORE PRINCIPLE: Decompose verification into exhaustive, independent acceptance criteria.

Every feature/task can be broken down into 5-20 specific, measurable acceptance criteria. LLM judge should verify each criterion independently, like a QA checklist.

Why Acceptance Criteria:

• Explicitness: "Button must be visible" is clearer than "button works"
• Completeness: Forces you to think through ALL aspects (UI, behavior, errors, edge cases, accessibility)
• Verifiability: Each criterion = one pass/fail check (no ambiguity)
• Feedback loops: Executor knows exactly what failed and how to fix it

How to Decompose Features into Acceptance Criteria:

1. UI Components (Buttons, Forms, Pages)

   • Existence: Component exists in correct location
   • Visual properties: Color, size, font, spacing match design
   • States: Default, hover, active, disabled, loading states render correctly
   • Behavior: Click/interaction triggers expected action
   • Error handling: Invalid inputs show proper error messages
   • Accessibility: ARIA labels, keyboard navigation, screen reader support
   • Responsiveness: Works on mobile, tablet, desktop viewports

   Example - Login Button:

   CRITERION 1: Button element exists at bottom of login form
   CRITERION 2: Button text is "Sign In" (not "Login" or other variants)
   CRITERION 3: Button uses primary brand color (#3B82F6)
   CRITERION 4: Button is disabled when form is invalid (empty email/password)
   CRITERION 5: Button shows loading spinner when authentication in progress
   CRITERION 6: Clicking button triggers login API call
   CRITERION 7: Successful login redirects to /dashboard
   CRITERION 8: Failed login displays error message below button
   CRITERION 9: Button has aria-label="Sign in to your account"
   CRITERION 10: Button is keyboard accessible (Enter key works)
   

2. API Endpoints

   • Request handling: Accepts correct HTTP method and content-type
   • Authentication: Requires valid auth token, rejects unauthorized requests
   • Input validation: Validates required fields, data types, formats
   • Success response: Returns correct status code (200/201/204) and data structure
   • Error responses: Returns appropriate error codes (400/401/404/500) with messages
   • Side effects: Database updates, event triggers, notifications work correctly
   • Performance: Responds within acceptable time (e.g., < 200ms)
   • Idempotency: Repeated requests don't cause duplicate effects (for POST/PUT)

   Example - POST /api/users (Create User):

   CRITERION 1: Endpoint accepts POST requests to /api/users
   CRITERION 2: Requires Content-Type: application/json header
   CRITERION 3: Requires valid JWT token in Authorization header
   CRITERION 4: Rejects requests without auth token (returns 401)
   CRITERION 5: Validates email format (returns 400 if invalid)
   CRITERION 6: Validates password strength (min 8 chars, returns 400 if weak)
   CRITERION 7: Returns 409 Conflict if email already exists
   CRITERION 8: On success, returns 201 with user object { id, email, created_at }
   CRITERION 9: Hashes password with bcrypt before storing (never stores plaintext)
   CRITERION 10: Sends welcome email to user after account creation
   CRITERION 11: Response includes Location header with /api/users/{id}
   CRITERION 12: Duplicate POST with same email returns existing user (idempotent)
   

Acceptance Criteria Template for LLM Judge:

llm_judge:
  - by: orchestrator-agent
    instruction: |
      Verify the following acceptance criteria. Each criterion must PASS independently.
      Mark each as PASS ✓ or FAIL ✗ with evidence.

      CRITERION 1: [Specific requirement]
      - What to verify: [Exact thing to check]
      - Expected: [Expected outcome]
      - How to verify: [Command/inspection method]
      - Evidence required: [What to show as proof]

      CRITERION 2: [Specific requirement]
      - What to verify: [Exact thing to check]
      - Expected: [Expected outcome]
      - How to verify: [Command/inspection method]
      - Evidence required: [What to show as proof]

      [     ]

       [ ]
        [   ]
        [ ]
        [ ]
        [    ]

      

      
        
        []
        []
                

          
         
          

LLM Judge Verification (ACCEPTANCE CRITERIA APPROACH)

Use LLM judge when:

• Verifying subjective quality criteria (code readability, UX polish, documentation clarity)
• Checking implementation correctness without deterministic output (UI rendering, user flows)
• Validating compliance with design specs, architecture patterns, or coding standards
• ESPECIALLY when you need to verify 5-20 independent acceptance criteria in one go

LLM Judge Best Practices (ACCEPTANCE CRITERIA APPROACH):

CRITICAL: Always structure LLM judge instructions as exhaustive acceptance criteria checklists.

1. Decompose the feature into 5-20 specific acceptance criteria

   • Each criterion = one independently verifiable requirement
   • Cover ALL aspects: functionality, UI, errors, edge cases, code quality, accessibility
   • Use the Acceptance Criteria Framework patterns (UI/API/Business Logic/Code Quality)

2. Format each criterion with 4 components:

   • What to verify: Exact thing to check (e.g., "Button text content")
   • Expected: Expected outcome (e.g., "Text is 'Sign In'")
   • How to verify: Method to check (e.g., "Inspect button element in rendered HTML")
   • Evidence required: What to show as proof (e.g., "Screenshot or HTML snippet showing button text")

3. Require PASS/FAIL marking for each criterion independently

   • Executor must mark each criterion as ✓ PASS or ✗ FAIL
   • For FAIL, executor must explain what went wrong and how to fix it
   • Final verdict: PASS only if ALL criteria passed

4. Include context commands for gathering evidence

   context_commands:
     - "cat src/components/LoginButton.tsx"
     - "npm run dev"  # Start dev server for UI inspection
     - "curl http://localhost:3000/api/login"
   

5. Choose appropriate judge

   • orchestrator-agent: For quick checks during execution (5-10 criteria)
   • external-agent: For thorough review requiring deep analysis (10-20 criteria)

Example - Login Button Implementation (UI Component):

llm_judge:
  - by: orchestrator-agent
    context_commands:
      - "cat src/components/LoginButton.tsx"
      - "cat src/styles/button.css"
      - "npm run dev"  # Start dev server
    instruction: |
      Verify the Login Button implementation against the following acceptance criteria.
      Mark each criterion as PASS ✓ or FAIL ✗ with evidence.

      CRITERION 1: Button element exists at bottom of login form
      - What to verify: Button position in DOM structure
      - Expected: Button is last child element of <form id="login-form">
      - How to verify: Inspect HTML structure at http://localhost:3000/login
      - Evidence required: HTML snippet or screenshot