spec-stateflow

by naozixu

Install this Skill

curl -fsSL -o spec-stateflow.zip https://skill.seembox.com/api/v1/skills/spec-stateflow/download && unzip spec-stateflow.zip

Download spec-stateflow.zip

SKILL.md About

---
name: spec-stateflow
description: "Structured software engineering workflow with state-driven execution: requirement analysis → technical design → task planning → execution with state navigation and session recovery. Triggers: new feature, complex architecture, multi-module integration, database/UI design, or any task requiring structured planning and execution. Trigger words: new feature, architecture design, requirement implementation, spec workflow, state recovery, compression recovery, task tracking"
alwaysApply: false
---

# Spec Workflow

**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
- Documentation updates
- Configuration changes

## 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 5 test scenarios covering all phases. 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:

| Placeholder | Meaning |
|------------|---------|
| `{SPEC_DIR}` | Spec file root directory |
| `{SPEC_NAME}` | Current spec name |
| `{SPEC_PATH}` | Full path = `{SPEC_DIR}/{SPEC_NAME}` |

**Spec file list:**

| File | Description |
|------|-------------|
| `{SPEC_PATH}/requirements.md` | Requirements document (Phase 1 output) |
| `{SPEC_PATH}/design.md` | Technical design document (Phase 2 output) |
| `{SPEC_PATH}/tasks.md` | Task breakdown & progress tracker (Phase 3 output, **single source of truth**) |

## Entry Points

| Your situation | Start here |
|----------------|-----------|
| New feature / complex task | **Phase 1** (full workflow: Phase 1 → 2 → 3 → 4) |
| Ready to execute (user confirmed plan) | **Phase 4 → Quick Start** |
| Session compressed / interrupted | **Phase 4 → Compression Recovery** |

> 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:

| Field | Specification | Example |
|-------|--------------|---------|
| **Task name** | Verb-object structure, ≤10 words | `Remove unused methods from IMultiAppInfo` |
| **Scope** | Files directly modified by this task | `IMultiAppInfoProxyInterface.java`, `MultiAppInfoProxy.java` |
| **Affected** | Files that need sync changes due to this task (imports, calls, etc.) | `NoticeService.java`, `BpmService.java` |
| **Specifics** | **Most critical field.** Precise down to method/field level | `Interface 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) | `[✓]` |
| **Verification** | How to verify (compile, test, grep, etc.) | `grep signatures + compile verification` |
| **Commit** | The actual commit message used | `feat(proxy): [...] remove unused methods` |
| **User corrections** | Count of user corrections; ≥2 triggers escalation | `0` |
| **Compression recoveries** | Count of compression recoveries; +1 after each | `0` |
| **Notes** | Dependencies, blockers, scope changes | `Depends 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
  - User corrections: 0 | Compression recoveries: 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: — | Compression recoveries: —
  - 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 and contains valid task entries (Scope + Specifics + Verification fields). If the file is missing or malformed, stop and ask the user.

### Quick Start

First time with a confirmed `tasks.md`:

```
1. Read {SPEC_PATH}/tasks.md → find first [ ] task
2. Mark it [~] → execute per Specifics description
3. When done: mark [✓], fill Verification + Commit, stage changes
4. Show diff → wait for user review and explicit commit approval
5. If user approves: commit → next task. If user rejects: revert status to [~], address feedback, repeat from step 3
6. User says "next" → repeat from step 1
```

**Session compressed?** Jump to [Compression Recovery](#compression-recovery).

### State Navigation

#### Where Am I?

```
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 State | What To Do Next | Key Output |
|---------------|-----------------|------------|
| Just received instruction | Classify task (simple / complex / fix / routine) → see Entry Points for entry decisions | Decision: plan or execute directly |
| Planning in progress (Phase 1-3) | Continue current phase → wait for user confirmation before next phase | Confirmed spec doc |
| Ready to implement | Read `{SPEC_PATH}/tasks.md`, mark first pending task as `[~]` | Task in progress |
| Just finished a task | Update `tasks.md` to `[✓]` → verify → commit → next task | Updated tracker |
| Hit an error | Stop → diagnose → fix → re-verify → **wait for user confirmation** → judge next step based on user's direction | Documented fix |
| Session interrupted / compressed | Jump to [Compression Recovery](#compression-recovery) | Recovered context |
| User asks unrelated question | Handle query → return to previous state, do NOT modify tracker | Continuity preserved |
| User starts a new feature mid-task | Pause current (mark `[~]`) → create new tracker → see Context Switching | New `{SPEC_PATH}` |
| User changes direction mid-task | Stop → document in Notes → wait for confirmation | Updated tracker |
| User corrects design assumption | Update `tasks.md` Notes **and** `design.md` → wait for confirmation | Synced docs |
| All tasks done | Generate final summary → wait for user confirmation → complete | See 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
   - Compression recoveries 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.

```
[Classified] --(simple/routine)--> [Executing] --(task done)--> [Update tracker] --(more tasks)--> [Executing]
      │                              │                                    └─(all done)--> [Complete]
      └─(complex/fix)--> [Planning] --(confirmed)--> [Executing]
                             └─(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]
```

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

### 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)
- **Compression recoveries:** +1 after each compression recovery

#### Timeliness Guarantee

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

| Event | Action | Why |
|-------|--------|-----|
| Start a task | `[ ]` → `[~]` **before** editing code | Prevents duplicate work |
| Finish a task | `[~]` → `[✓]`, fill Verification + Commit **immediately**, before committing code or starting next task | Defines completion |
| User changes scope | Record in Notes **immediately**, increment User corrections | Prevents drift |
| Session compresses | `[~]` → `[ ]` if uncertain about state | Prevents 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 Step | Full Step Mapping |
|-----------|------------------|
| Read and confirm progress | Step 2 |
| Verify code state | Step 3-4 |
| Determine next step | Step 5-7 |

> Step 1 (check recovery count) must be performed first before any other step.

#### Full Compression Recovery Flow (7 Steps)

**Step 1: Check recovery count, decide whether to continue**
- Count the real compression recovery count since last session reset using the method below, then write the result into the current task's `Compression recoveries` field in `{SPEC_PATH}/tasks.md`
- **Report count:** Tell user "This task has been compression-recovered X times"
- **Decision branch:**
  - **If < 6:** Continue to Step 2
  - **If ≥ 6:** **Stop execution immediately**, then:
    1. Update `{SPEC_PATH}/tasks.md`: mark current task as `[~]`, update compression recovery count
    2. Tell user: "Current task has been compression-recovered X times (≥6). Accumulated context errors may make state reconstruction unreliable. Please reset session — I will continue from Spec files in a new session."
    3. **Do not execute any code modifications** — wait for user to reset session
  - **6 is a hard threshold, do not override**

**Compression Recovery Count Method (for Step 1):**

Count real context compaction events, never estimate manually.

**Steps:**
1. Identify the agent's session storage directory (e.g., for Claude Code: `~/.claude/projects/{project-hash}/sessions/`)
2. Find session files that contain the current requirement ID
3. Count compression markers within those files (e.g., for Claude Code: count occurrences of `<compacted>` or similar context-compaction tags)
4. Sum all matching compression events = true compression recovery count for this requirement
5. Write the result into the current task's `Compression recoveries` field in `{SPEC_PATH}/tasks.md`

**If the agent platform's session storage structure is unknown**, fall back to reading the `Compression recoveries` field values from all tasks in `tasks.md` and use the maximum value + 1 as the current count. Report to user that this is an estimate.

**Step 2: 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 3

**Step 3: 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 Step 3 and Step 4 → go to Step 5
- **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 4: 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 5: 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 6: 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 7: 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

| Scenario | Rule |
|----------|------|
| User starts a new feature | Pause current task (mark `[~]`), create new tracker for new work |
| User raises multiple parallel requests | Confirm 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 3 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

_meta.json Metadata

{
  "ownerId": "kn7fr5xv3y4wnve5j7ger18a8985te4v",
  "publishedAt": 1777782817885,
  "slug": "spec-stateflow",
  "version": "1.0.2"
}