spec-workflow

$2a

Read before writing code if

• You are unsure whether the task should go straight to coding or should first go through requirements, design, and task planning.

• The request mentions a new page, a new system, a redesign, a workflow, or a multi-module refactor.

Then also read

• Frontend page or visual design work -> ../ui-design/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/ui-design/SKILL.md)

• Advanced data-model work -> ../data-model-creation/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/data-model-creation/SKILL.md)

Do NOT use for

• Small bug fixes with clear scope.

• One-file documentation updates.

• Straightforward config changes.

• Tiny refactors where the user already gave exact implementation instructions.

Common mistakes / gotchas

• Jumping into coding before acceptance criteria are explicit.

• Skipping user confirmation between requirements, design, and tasks.

• Writing vague tasks that do not map back to user-visible outcomes.

• Treating UI work as purely technical implementation without clarifying design intent.

Minimal checklist

• Decide whether the change really needs the full spec flow.

• If yes, stop and produce requirements first.

• If the change is small, low-risk, and acceptance is already clear, allow direct execution without forcing spec artifacts.

• Use EARS-style acceptance criteria.

• Get confirmation before moving to the next phase.

When to use this skill

Use this workflow for structured development when you need to:

• Define or refine a new feature

• Design complex architecture

• Coordinate changes across modules

• Plan database or UI-heavy work

• Improve requirement quality and acceptance boundaries

Decision rule

Use the full workflow when

• The task is medium or large

• The impact spans multiple modules

• Acceptance boundaries are fuzzy

• The user wants disciplined planning before implementation

Skip the full workflow when

• The task is small, low-risk, and already precise

• Goal, scope, and acceptance are already clear enough to execute directly

• The user explicitly wants a direct code change with no planning phase

Core workflow

Phase 1: Requirements

Create specs/<spec_name>/requirements.md.

What to do:

• Restate the problem and scope

• Write user stories

• Write acceptance criteria in EARS style

• Clarify business rules, constraints, and non-goals

EARS pattern:

While <optional precondition>, when <optional trigger>, the <system name> shall <system response>

Example:

When the user submits the form, the booking system shall validate required fields before creating the record.

Phase 2: Design

Create specs/<spec_name>/design.md.

What to do:

• Describe architecture and module boundaries

• Explain technology choices and trade-offs

• Define data model, API, security, and testing strategy as needed

• Use Mermaid only when a diagram materially improves clarity

Phase 3: Tasks

Create specs/<spec_name>/tasks.md.

What to do:

• Break the design into executable tasks

• Keep tasks specific and reviewable

• Link each task back to the relevant requirement

• Update task status as work progresses

Task format:

# Implementation Plan

- [ ] 1. Task title

  - Specific work item

  - Another concrete step

  - _Requirement: 1

Phase 4: Execution

Only start implementation after the user confirms the task plan.

During execution:

• Keep task status current

• Finish one meaningful unit at a time

• Preserve traceability from change -> task -> requirement

Working rules for the agent

• Ask follow-up questions when the request is underspecified; do not guess core product behavior.

• Require confirmation between requirements, design, and task breakdown.

• Pull in ui-design early when the change includes end-user pages or visual decisions.

• Keep documents concise but testable.

• Prefer user-visible outcomes over implementation-detail task names.

Output expectations

• requirements.md -> problem, scope, user stories, EARS acceptance criteria

• design.md -> architecture, technical approach, data/API/security/test notes

• tasks.md -> actionable implementation checklist tied to requirements