common-skills/skills/sdlc/SKILL.md

---
name: sdlc
description: Systematic software development lifecycle assistant. Guides through requirements analysis, system design, task decomposition, and implementation planning. Use when a user needs to build a new feature, system, or product from scratch, or when they say "help me build", "design a system", "break down this feature", "plan this project", "需求分析", "系统设计", "任务分解", "实现计划", "帮我做", "帮我设计".
metadata:
  author: common-skills
  version: "1.0"
---

# SDLC Skill

Guide the user through a complete, systematic software development lifecycle: requirements → design → task breakdown → implementation plan. Produce concrete, actionable artifacts at each phase.

## Phase Overview

Run phases sequentially. Each phase produces a written artifact. **After completing each phase, present the artifact to the user and wait for explicit confirmation (e.g. "ok", "looks good", "continue", "确认") before proceeding to the next phase.** Do not advance automatically. Do not skip phases unless the user explicitly says a phase is already done.

```
Phase 1: Requirements Analysis  →  specs/requirements.md
Phase 2: System Design          →  specs/design.md
Phase 3: Task Decomposition     →  specs/tasks.md
Phase 4: Implementation Plan    →  specs/impl-plan.md
Phase 5: Implementation         →  source code
Phase 6: Verification           →  specs/impl-plan.md (DoD checkboxes updated)
```

**State tracking:** Maintain `specs/STATUS.md` throughout the process. Update it after each phase completes. Format:

```markdown
# SDLC Status

- [x] Phase 1: Requirements — completed
- [x] Phase 2: Design — completed
- [ ] Phase 3: Tasks — in progress
- [ ] Phase 4: Implementation Plan
- [ ] Phase 5: Implementation
- [ ] Phase 6: Verification
```

**Output location:** Write all artifacts to `./specs/` in the current working directory. If the user specifies a path, use that instead.

---

## Phase 1 — Requirements Analysis

**Goal:** Clarify what to build and why, before any design decisions.

Steps:
1. Identify the problem statement and user goals.
2. List functional requirements (what the system must do).
3. List non-functional requirements (performance, security, scalability, availability).
4. Identify constraints (tech stack, timeline, team size, budget).
5. Define out-of-scope items explicitly.
6. List open questions that need answers before design can proceed.

Output format — `requirements.md`:

```markdown
# Requirements: {Project Name}

## Problem Statement
{1–3 sentences: what problem, for whom, why it matters}

## Functional Requirements
- FR-1: ...
- FR-2: ...

## Non-Functional Requirements
- NFR-1: ...

## Constraints
- ...

## Out of Scope
- ...

## Open Questions
- [ ] ...
```

---

## Phase 2 — System Design

**Goal:** Define the architecture and key technical decisions.

Steps:
1. Choose architecture style (monolith, microservices, event-driven, etc.) and justify.
2. Draw a component diagram (PlantUML) showing major components and their interactions.
3. Define the data model (entities, relationships, key fields).
4. Identify external dependencies (third-party APIs, databases, queues, auth providers).
5. Document key technical decisions as ADRs (Architecture Decision Records) — one sentence each: decision + rationale.
6. Identify risks and mitigations.

Output format — `design.md`:

```markdown
# Design: {Project Name}

## Architecture
{Style chosen and rationale}

### Component Diagram
```plantuml
@startuml
...
@enduml
```

## Data Model
```plantuml
@startuml
entity ...
@enduml
```

## External Dependencies
| Dependency | Purpose | Notes |
|---|---|---|

## Architecture Decision Records
- ADR-1: {Decision} — {Rationale}
- ADR-2: ...

## Risks
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
```

---

## Phase 3 — Task Decomposition

**Goal:** Break the system into concrete, independently deliverable tasks.

Steps:
1. Group work into milestones (e.g., M1: Foundation, M2: Core Features, M3: Polish).
2. Within each milestone, list tasks. Each task must be:
   - Independently completable by one developer
   - Estimable (provide story points or hours)
   - Linked to at least one functional requirement
3. Identify dependencies between tasks (task B requires task A).
4. Flag tasks that are on the critical path.
5. Identify tasks that can be parallelized.

Output format — `tasks.md`:

```markdown
# Tasks: {Project Name}

## Milestone 1 — {Name} (Target: {date or sprint})

| ID | Task | Est. | Depends On | FR | Critical |
|---|---|---|---|---|---|
| T-1 | ... | 2h | — | FR-1 | ✓ |
| T-2 | ... | 4h | T-1 | FR-2 | |

## Milestone 2 — {Name}
...

## Dependency Graph
```plantuml
@startuml
[T-1] --> [T-2]
...
@enduml
```

## Parallelizable Work
- T-3, T-4, T-5 can run in parallel after T-1
```

---

## Phase 4 — Implementation Plan

**Goal:** Produce a concrete, ordered execution plan a developer can follow immediately.

Steps:
1. Order tasks into a sprint/week plan based on dependencies and priorities.
2. For each task, provide:
   - Acceptance criteria (how to know it's done)
   - Key implementation notes (approach, gotchas, patterns to use)
   - Definition of Done checklist
3. Identify the first task to start (the "day 1" task).
4. List any setup/scaffolding needed before coding begins.

Output format — `impl-plan.md`:

```markdown
# Implementation Plan: {Project Name}

## Setup Checklist
- [ ] ...

## Sprint 1

### T-1: {Task Name}
**Acceptance Criteria:**
- ...

**Implementation Notes:**
- ...

**Definition of Done:**
- [ ] Code written and reviewed
- [ ] Tests passing
- [ ] Deployed to staging

...
```

---

## Phase 5 — Implementation

**Goal:** Write the actual code following the impl-plan.

- Implement tasks in the order defined in `specs/impl-plan.md`, respecting dependencies.
- After completing each task, tick its Definition of Done checkboxes in `specs/impl-plan.md`.
- Update `specs/STATUS.md` to reflect current progress.
- Do not proceed to Phase 6 until all tasks in impl-plan are implemented.

---

## Phase 6 — Verification

**Goal:** Confirm every task's Acceptance Criteria is met. Incomplete tasks must be completed before marking done.

Steps:
1. Re-read `specs/impl-plan.md` in full.
2. For **every** task and **every** DoD checkbox:
   - Check whether the corresponding artifact/code actually exists.
   - If it exists and passes: mark `[x]`.
   - If it is missing or failing: **complete the work first**, then mark `[x]`.
   - Never mark `[x]` for work that has not been done.
3. Update `specs/tasks.md` — add a `Done` column and mark each row ✓ when its DoD is fully checked.
4. Update `specs/STATUS.md` — mark Phase 5 and Phase 6 complete only after all DoD items are `[x]`.
5. Report a summary: total criteria, passed, completed-during-verification, any remaining failures.

---

## Behavior Guidelines

- **Context budget.** The model context window is finite (~200K tokens). To avoid overflow:
  - Never read source code files in bulk during planning phases (1–4). Only read `specs/` artifacts and targeted config/metadata files.
  - During Phase 5 (implementation), implement and verify one task at a time. Do not load all source files simultaneously — read only the files relevant to the current task.
  - During Phase 6 (verification), run tests and check artifacts one task at a time rather than loading everything at once.
  - If context is running low (many files already read), summarize completed work, write state to `specs/STATUS.md`, and tell the user: "Context limit approaching — please start a new session and say 'continue' to resume from Phase N."
- **Track state.** After each phase completes, update `specs/STATUS.md`. On session start, read `specs/STATUS.md` first to resume from the correct phase.
  1. Check if `specs/STATUS.md` exists.
  2. If yes: read it, identify the last completed phase, and tell the user: "Resuming from Phase N — [phase name]. Last completed: [summary]." Then continue from where it left off.
  3. If no: this is a fresh start — proceed with Phase 1.
- **Resume on session start.** At the beginning of every session, before doing anything else: If the user's input is ambiguous (e.g., "build a chat app"), ask 2–3 targeted clarifying questions before starting Phase 1. Do not invent requirements.
- **Inline Q&A for unknowns.** When there are unclear decisions within a phase, embed them directly in the artifact file under a `## ❓ Questions` section at the bottom. Each question must include a suggested answer. Example:
  ```markdown
  ## ❓ Questions
  - Q1: Should the API be REST or GraphQL?
    Suggested: REST — simpler for this use case.
  - Q2: Do we need multi-tenancy from day one?
    Suggested: No — single-tenant first, add later if needed.
  ```
  After writing the file, tell the user: "Please review the questions at the bottom of the file, fill in or adjust the answers, then reply 'done' to continue." Wait for the user to confirm (e.g. "done", "approve", "已回答", "继续") before proceeding. Once confirmed, re-read the file, incorporate the answers, and remove the `## ❓ Questions` section before moving to the next phase.
- **Be concrete.** Use actual names, technologies, and numbers from the user's context — not generic placeholders.
- **Stay lean.** Prefer simple designs over complex ones. Flag complexity only when requirements demand it.
- **Surface trade-offs.** When multiple approaches exist, briefly state the trade-off and recommend one.
- **No code until design is complete.** Do NOT generate any implementation code until Phases 1–3 are fully confirmed by the user. Phase 4 produces a plan with notes, not code — actual code is only written after the user explicitly requests it post-planning.
- **Iterate on request.** If the user says "change X" or "add Y" to an existing artifact, update only the affected artifact and note what changed.
- **Change Requests (CR).** When the user requests a new feature or significant change after Phase 4 is complete, treat it as a CR:
  1. Create `specs/crs/CR-<N>-<short-title>.md` (e.g. `specs/crs/CR-1-add-semantic-search.md`) with the same structure as a mini SDLC: requirements delta, design delta, new/updated tasks, impl notes.
  2. Update `specs/STATUS.md` to list the CR and its phase status.
  3. Follow the same phase-by-phase confirmation flow for the CR before implementing.
  4. On completion, update the original `specs/tasks.md` and `specs/impl-plan.md` to reflect the additions.
- **Language.** Respond in the same language the user used.

See [assets/phase-checklist.md](assets/phase-checklist.md) for a quick reference checklist for each phase.