Spec Stateflow#

Important: You must follow these rules. Each phase must be confirmed by the user before proceeding to the next phase.

When to Use This Skill#

Use this skill for structured development workflow when you need to:

• Develop new features from scratch
• Design complex architecture
• Integrate multiple modules
• Ensure high-quality requirement analysis and acceptance criteria

Do NOT use for:

• Simple requirements
• Simple bug fixes (single file / single method / obvious root cause)
• Documentation updates
• Configuration changes

Fix vs Simple bug fix boundary: A "Fix" task (use Spec) involves cross-module impact, systematic tech debt, or requires design before coding. A "Simple bug fix" (no Spec) is a localized, obvious fix in ≤1 file with no architectural implications.

How to Use This Skill#

1. Follow the four phases in order — each phase requires user confirmation before proceeding:

   • Phase 1: Write requirements using EARS syntax → requirements.md
   • Phase 2: Design technical solution (architecture, API, DB, etc.) → design.md
   • Phase 3: Break down tasks with field-level specifics → tasks.md
   • Phase 4: Execute tasks with state tracking, compression recovery, and context switching

2. [HIGHEST PRIORITY]Real-time tasks.md updates — After completing each small task, you MUST immediately update {SPEC_PATH}/tasks.md, before compilation, testing, or starting the next task. Not updated = not done. See Phase 4 State Assurance for details

Testing: This skill includes test-prompts.json with 10 test scenarios covering all phases and edge cases. Use them to validate skill behavior.

Path Convention#

All Spec files use the following placeholders. Actual paths are defined in the user's project configuration:

PlaceholderMeaning{SPEC_DIR}Spec file root directory{SPEC_NAME}Current spec name{SPEC_PATH}Full path = {SPEC_DIR}/{SPEC_NAME}

Spec file list:

FileDescription{SPEC_PATH}/requirements.mdRequirements document (Phase 1 output){SPEC_PATH}/design.mdTechnical design document (Phase 2 output){SPEC_PATH}/tasks.mdTask breakdown & progress tracker (Phase 3 output, single source of truth)

Entry Points#

Your situationStart hereNew feature / complex taskPhase 1 (full workflow: Phase 1 → 2 → 3 → 4)Ready to execute (user confirmed plan)Phase 4 → Quick StartUser authorized continuous batch / driver-monitor automationPhase 4 → Continuous Operation ModeSession compressed / interruptedPhase 4 → Compression RecoveryUser says "updatecode" / "continue" / "resume"Phase 4 → Quick Start (read tasks.md → locate breakpoint → continue)

For all runtime states (error, context switch, task completion, etc.), see Phase 4 → State Navigation.

Workflow Rules#

1. When you determine that the user's input implies a new requirement (not explicitly stated), you may work independently following standard software engineering practices. Confirm with the user when necessary.

2. When the user explicitly states a new requirement, you must follow the full workflow: understand the problem and requirements clearly, and confirm with the user before proceeding to the next phase.

---

Phase 1: Requirements Document and Acceptance Criteria Design#

First complete the requirements design using EARS (Easy Approach to Requirements Syntax) method. You must confirm requirement details with the user. After final confirmation, the requirements are finalized, then proceed to the next phase.

Save to {SPEC_PATH}/requirements.md. After confirming with the user, proceed to the next phase.

If user rejects or requests changes: Update requirements.md and re-confirm. Do NOT proceed to Phase 2 until user explicitly approves.

Reference format:

markdown

# Requirements Document

## Introduction

Requirement description

## Requirements

### Requirement 1 - Requirement Name

**User Story:** User story content

#### Acceptance Criteria

1. Use EARS syntax: While <optional precondition>, when <optional trigger>, the <system name> shall <system response>. For example: When "Mute" is selected, the laptop shall suppress all audio output.
2. ...
...

---

Phase 2: Technical Solution Design#

After completing the requirements design, based on the current technical architecture and the confirmed requirements above, design the technical solution. It should be concise but accurately describe the technical architecture (e.g., architecture, tech stack, technology selection, database/interface design, test strategy, security). Use mermaid diagrams when necessary.

Must include chapters: Background, Design Goals, Business Model, System Design (precise to package path, class name, method signature), Refactoring Design (if applicable), Deployment Plan (for large tasks), Risk Assessment (for large tasks).

Save to {SPEC_PATH}/design.md. You must confirm with the user clearly, then proceed to the next phase.

If user rejects or requests changes: Update design.md and re-confirm. Do NOT proceed to Phase 3 until user explicitly approves.

Reference format:

markdown

# Technical Solution Design

## Background
Why this design is needed — business context and problem statement

## Design Goals
- Goal 1: ...
- Goal 2: ...

## Business Model
Core domain models, entity relationships, key data flows

## System Design
### Architecture Overview
(mermaid diagram or component description)

### Module: {module-name}
- **Package:** `com.example.module`
- **New classes:**
  - `ClassName` — responsibility description
  - `InterfaceName` — method signatures: `ReturnType methodName(ParamType param)`
- **Modified classes:**
  - `ExistingClass` — add method `newMethod()`, change field `field` scope

### API Design
| Endpoint | Method | Request | Response |
|----------|--------|---------|----------|
| `/api/xxx` | POST | `{field: type}` | `{field: type}` |

### Database Design
Table name, columns, indexes, migration steps

### Test Strategy
Unit test scope, integration test plan, verification methods

## Refactoring Design (if applicable)
What to refactor, why, and how to do it incrementally

## Deployment Plan (for large tasks)
Environments, rollout steps, rollback plan

## Risk Assessment (for large tasks)
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| ... | High/Med/Low | High/Med/Low | ... |

---

Phase 3: Task Breakdown#

After completing the technical solution design, based on the requirements document and technical solution, break down specific tasks. You must confirm with the user clearly, then save to {SPEC_PATH}/tasks.md. After confirming with the user, proceed to the next phase.

If user rejects or requests changes: Adjust task breakdown and re-confirm. Do NOT proceed to Phase 4 until user explicitly approves.

Task Field Specification#

Every task in {SPEC_PATH}/tasks.md must contain the following fields:

FieldSpecificationExampleTask nameVerb-object structure, ≤10 wordsRemove unused methods from IMultiAppInfoScopeFiles directly modified by this taskIMultiAppInfoProxyInterface.java, MultiAppInfoProxy.javaAffectedFiles that need sync changes due to this task (imports, calls, etc.)NoticeService.java, BpmService.javaSpecifics****Most critical field. Precise down to method/field levelInterface remove methodA(), methodB(); add methodC(String)Status[✓] Done / [ ] Not started / [~] In progress or paused / [⏭] Skipped (user decision only; dependencies not auto-blocked, flag in final summary)[✓]VerificationHow to verify (compile, test, grep, etc.)grep signatures + compile verificationCommitBackfill after git commit: actual commit message + short hashfeat(proxy): remove unused methods (a1b2c3d)User correctionsCount of user corrections; ≥2 triggers escalation0NotesDependencies, blockers, scope changesDepends on task 1

Critical field — Specifics: Must be precise down to method/field level. After session compression, recovery depends entirely on this field to reconstruct what was done and what remains.

Status values:

• [ ] — Not started
• [~] — In progress
• [✓] — Done
• [⏭] — Skipped (only when user explicitly decides to skip; agent cannot self-skip; skipped tasks are excluded from execution — dependencies are not auto-blocked, but flag them in the final task summary)

Task Format Reference#

markdown

# Implementation Plan

- [✓] 1. Remove unused methods from IMultiAppInfo
  - Scope: `IMultiAppInfoProxyInterface.java`, `MultiAppInfoProxy.java`
  - Affected: `NoticeService.java`
  - Specifics: Interface remove getCachedV2AppInfo(), listV1OfflineApps(); impl class sync
  - Verification: grep signatures + compile verification
  - Commit: feat(proxy): remove unused methods (a1b2c3d)
  - User corrections: 0
  - Notes: User requested keeping getV1AppInfo 3-param overload
  - _Requirement: R1

- [ ] 2. Add getAppName method
  - Scope: `IMultiAppInfoProxyInterface.java`, `MultiAppInfoProxy.java`
  - Affected: —
  - Specifics: Interface add getAppName(String); impl class add getAppName(String)
  - Verification: —
  - Commit: —
  - User corrections: —
  - Notes: Depends on task 1 completion
  - _Requirement: R2

---

Phase 4: Task Execution#

Execute tasks in order from {SPEC_PATH}/tasks.md. This phase covers execution mechanics, state navigation, and session recovery.

Validation: Before executing, confirm {SPEC_PATH}/tasks.md exists, contains valid task entries (Scope + Specifics + Verification fields), and all tasks have valid status markers ( [ ] / [~] / [✓] / [⏭]). If the file is missing, malformed, or has tasks with missing/invalid status markers, stop and fix the format before proceeding.

Quick Start#

First time with a confirmed tasks.md:

text

0. Validate tasks.md format — ensure every task has a valid status marker [ ]/[~]/[✓]/[⏭]. Fix any missing/invalid markers before proceeding.
1. Read {SPEC_PATH}/tasks.md → if any [~] task exists, continue it; otherwise find first [ ] task
2. Mark it [~] → execute per Specifics description
3. When done: mark [✓], fill Verification, stage changes
4. Show diff → wait for user review and explicit commit approval (**skipped in [Continuous Operation Mode](#continuous-operation-mode)**)
5. If user approves: commit → backfill Commit field with actual message + short hash → next task. If user rejects: revert status to [~], address feedback, repeat from step 2
6. User says "next" → repeat from step 1

Session compressed? Jump to Compression Recovery. Continuous batch authorized by the user (e.g. "you may continue implementing" / "complete the rest without asking"), or running under driver/monitor automation? Jump to Continuous Operation Mode.

State Navigation#

Where Am I?

text

Received user instruction
│
├─ Is the scope clear and small? ──→ YES → Do NOT use this skill, execute directly
│                                    NO
├─ Does it need design/architecture? → YES → Plan first → Write tasks.md → Execute
│                                    NO (unclear)
└─ Investigate → Reclassify

Current StateWhat To Do NextKey OutputJust received instructionClassify task (simple / complex / fix / routine) → see Entry Points for entry decisionsDecision: plan or execute directlyPlanning in progress (Phase 1-3)Continue current phase → wait for user confirmation before next phaseConfirmed spec docReady to implementRead {SPEC_PATH}/tasks.md, mark first pending task as [~]Task in progressJust finished a taskUpdate tasks.md to [✓] → verify → commit → next taskUpdated trackerHit an errorStop → diagnose → fix → re-verify → wait for user confirmation → judge next step based on user's directionDocumented fixSession interrupted / compressedJump to Compression RecoveryRecovered contextUser asks unrelated questionHandle query → return to previous state, do NOT modify trackerContinuity preservedUser starts a new feature mid-taskPause current (mark [~]) → create new tracker → see Context SwitchingNew {SPEC_PATH}User changes direction mid-taskStop → document in Notes → wait for confirmationUpdated trackerUser corrects design assumptionUpdate tasks.md Notes and design.md → wait for confirmationSynced docsAll tasks doneGenerate final summary → wait for user confirmation → completeSee Task Completion

Task Completion

When all tasks in tasks.md are [✓] or [⏭]:

1. Generate final summary including:

   • Total tasks: done / skipped
   • Skipped tasks list (if any) — flag each with its original scope and reason for skip
   • User corrections total across all tasks

2. Present summary to user and wait for confirmation

3. After user confirms: the spec workflow is complete. Spec files ( requirements.md, design.md, tasks.md) are retained as project documentation

State Transition Rules

The State Navigation table is the primary reference. The flow diagram below illustrates the core state machine; all scenarios in the table are authoritative.

text

[Classified] --(simple/routine)--> [Direct Execution] --> [Done]
      │
      └─(complex/fix)--> [Planning] --(confirmed)--> [Executing] --(task done)--> [Update tracker] --(more tasks)--> [Executing]
                             │                                                                    └─(all done)--> [Complete]
                             └─(rejected)--> [Revise plan]

[Executing] --(error)--> [Diagnosing] --(fixed)--> [Update tracker] --> [Executing]
                                    └─(stuck)--> [Ask user] --(user responds)--> [Judge next step based on user's direction]

[Complete] --(user confirms)--> [Done]

[Any state] --(unrelated user query)--> [Handle query] --> [Return to prior state]
[Any state] --(user changes direction)--> [Stop + document] --> [Wait for confirmation]
[Any state] --(user corrects design assumption)--> [Update tasks.md + design.md] --> [Wait for confirmation]
[Any state] --(session compressed/interrupted)--> [Recovery] --(tracker reconciled)--> [Resume prior state]

Scope note: The diagram above covers only tasks that enter the Spec workflow (Complex / Fix). Simple and Routine tasks are executed directly without entering this state machine.

Critical rule: You cannot transition from [Executing] to the next task without updating the tracker. Updating tasks.md is the definition of task completion.

Continuous Operation Mode#

Skips per-task show diff → wait approval. Auto-advances to next [ ] task. All other tracker disciplines remain mandatory.

Activation

• User explicitly authorizes continuous batch (e.g. you may continue implementing / complete the rest without asking)
• Invoked by driver/monitor automation

Ambiguous confirmations ( OK / continue / okay) do NOT activate. Authorization does not survive session compression.

Behavior Diff

DisciplineStatusMark [~] / [✓], fill Verification + Commit✅ KeptRun verification (compile / test / grep)✅ KeptPer-task independent commit✅ KeptIncrement User corrections on rejection✅ KeptShow diff → wait approval❌ SkippedWait for next between tasks❌ Auto-advance

Auto-Pause Triggers

Reverts to Default Mode immediately on:

TriggerActionCompilation / verification failsRollback to [~], record in NotesUser corrections ≥ 2Escalate per project configScope expansionRecord drift, wait for confirmationRisky ops (force push, reset --hard, schema migration, etc.)Stop and askUser interruptsStop after current task's commitAll tasks completeSwitch to Task CompletionSession compression recoveryRevert to Default, re-confirm

State Assurance#

The Tracker ( tasks.md)

{SPEC_PATH}/tasks.md is the primary state reference. If memory, conversation, and tracker disagree, pause and reconcile with the user — never silently override user intent.

Key reminders for execution:

• Specifics is the most critical field — must be precise down to method/field level; after session compression, recovery depends entirely on this field
• Status values: [ ] Not started / [~] In progress (set before editing code) / [✓] Done (set before committing) / [⏭] Skipped (user decision only)
• User corrections: ≥2 triggers escalation (user's project configuration defines the escalation behavior)

Timeliness Guarantee

{SPEC_PATH}/tasks.md must be updated in real time — never retroactively:

EventActionWhyStart a task[ ] → [~] before editing codePrevents duplicate workFinish a task (before commit)[~] → [✓], fill Verification immediatelyDefines completionFinish a task (after commit)Backfill Commit field with actual message + short hashTraceabilityUser changes scopeRecord in Notes immediately, increment User correctionsPrevents driftSession compresses[~] → [ ] if uncertain about statePrevents false progress

Precedence: This takes precedence over compilation, testing, and starting the next task. A task whose tracker entry is not updated is considered NOT done.

Prohibited:

• Never reconstruct progress after compression without re-verifying code state first
• Never write progress retroactively after compression — progress not written before compression is unreliable

Compression Recovery#

{SPEC_PATH}/tasks.md is the operational basis for recovery.

Trigger: System message "This session is being continued from a previous conversation" or when memory is fuzzy.

Quick StepFull Step MappingRead and confirm progressStep 1Verify code stateStep 2-3Determine next stepStep 4-6

Full Compression Recovery Flow (6 Steps)

Step 1: Read Spec files, confirm {SPEC_PATH}/tasks.md progress

• Read {SPEC_PATH}/requirements.md, {SPEC_PATH}/design.md, {SPEC_PATH}/tasks.md
• tasks.md is the only trustworthy state source — summary progress descriptions are NOT reliable
• Special cases:
  • If Spec files don't exist:
    • If context indicates a Simple task (no requirement ID, no Spec): run git status and git diff, determine progress from working tree state, continue directly
    • Otherwise (Complex/Fix): Spec planning hasn't started. Re-run "Where Am I?" classification
  • If files exist but tasks.md is missing: Rebuild tasks.md from design.md, note in remarks "table rebuilt after compression recovery"
  • If all files exist: Proceed to Step 2

Step 2: Verify actual code state

• Run git status and git diff to confirm working tree state
• If no [✓] rows in tasks.md (no tasks completed yet): first [ ] or [~] row is the next task, skip the rest of this step and all of Step 3 → go to Step 4
• If [✓] rows exist: Only verify the last [✓] row (state boundary), re-execute verification per "Scope + Specifics + Verification" fields
• If verification passes → trust all prior [✓]; if fails → change that task status to [ ], consider backtracking
• If tasks.md doesn't match actual state, fix tasks.md first, then continue

Step 3: Do not trust summary "completed" conclusions

• Summary claims of "completed", "aligned", "fixed" — only verify the last completed task
• Especially for precision-critical conclusions (interface/impl alignment, method signature matching, compile status)
• If verification fails, revert that task to [ ], consider backtracking

Step 4: Re-confirm next task

• Explicitly state the next task name and scope
• Do not continue based on vague summary descriptions (e.g., "continue fixing remaining interfaces")

Step 5: Use programmatic verification, not manual reading

• For "does it exist", "is it aligned", "does it match" — prefer Bash tools (grep, javap, diff) for programmatic verification
• Never judge interface/impl alignment, method existence, or parameter matching by reading alone

Step 6: Update tasks.md before executing

• Before making any code changes, update {SPEC_PATH}/tasks.md first
• Ensure tasks.md is consistent with actual state

Context Switching#

ScenarioRuleUser starts a new featurePause current task (mark [~]), create new tracker for new workUser raises multiple parallel requestsConfirm priority and order with user; create separate Spec directories (different {SPEC_NAME}) for each; execute sequentially, never mix tasks.md

Key principle: One tasks.md per requirement. Different requirements must have different {SPEC_PATH}.

Do not abandon unfinished tasks. Unless user explicitly says "cancel" or "skip", mark unfinished tasks as [~] and record progress.

When returning to a previous task, re-verify state. Verify the last [✓] row per Step 2 of Compression Recovery.

---

Key Principles#

1. [HIGHEST PRIORITY]Real-Time Task Tracking — Updating {SPEC_PATH}/tasks.md is the definition of task completion; it takes precedence over all other operations
2. User Confirmation Required — Each phase must be confirmed by the user before proceeding to the next
3. Tracker is truth — When memory conflicts with tracker, trust the tracker; pause and reconcile with the user on conflicts
4. Verify with tools — Prefer programmatic verification (grep, diff, compiler); never rely on reading or memory for precision questions
5. Cross-check conclusions — Any conclusion from indirect observation must be independently verified