# Sdd Task Planner

> Intelligent planning engine that uses historical patterns and project rules to generate implementation tasks.

- Skill: `leoheart0125/sdd-task-planner` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add leoheart0125/sdd-task-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leoheart0125/sdd-task-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: leoheart0125 (https://skillmd.com/u/leoheart0125)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leoheart0125/sdd-task-planner

---


# SDD Task Planner

This skill transforms specifications into actionable plans, but unlike a simple generator, it **learns** and **enforces rules**. It checks the Knowledge Base for similar past features, reads `project_rules.md` for architectural constraints, and applies clarification when needed.

## Core Responsibilities

1.  **Rule-Aware Planning**: Read `project_rules.md` **first** — especially Architecture and Coding Standards — before generating any task.
2.  **Pattern Matching**: Query `sdd-knowledge-base` for tasks similar to the current feature (by tags).
3.  **Smart Generation**: If a pattern exists, hydrate it. If not, generate new tasks from spec artifacts.
4.  **Path Validation**: Every task must include a `target_path` that conforms to the architecture conventions defined in `project_rules.md`.
5.  **Optimization**: Order tasks to minimize context switching.

## Commands

-   `/sdd-plan`: Generate or update the implementation plan (`tasks.json`).
-   `/sdd-plan-optimize`: Re-sort tasks based on dependencies and developer availability.

## Planning Logic

When `/sdd-plan` is called:

### Step 1: Read Project Rules (MANDATORY FIRST STEP)
1.  Load `project_rules.md` from `.sdd/context/`.
2.  Extract architecture conventions from the Architecture section of `project_rules.md` (e.g., directory structure patterns, layer ordering).
3.  Extract coding standards and naming conventions.
4.  These rules constrain all subsequent task generation.

### Step 2: Knowledge Lookup (MANDATORY — Index-Based)
1.  Read `.sdd/knowledge/index.json` (the lightweight index).
2.  Filter `patterns` entries whose `tags` match the current feature's domain keywords.
3.  Filter `lessons` entries whose `tags` match OR whose `trigger` matches `"planning-*"` or the current feature's domain.
4.  Load ONLY the matched files (via the `file` path in each index entry). Do NOT scan the full `patterns/` or `lessons/` directories.
5.  Summarize relevant findings — reuse proven strategies and avoid past mistakes.
6.  **Output the knowledge match results** before proceeding:

```
📚 **Knowledge Loaded** (stage: plan)

| Type | ID | Matched Tags | Summary |
|------|----|-------------|---------|
| <type> | <id> | `<tag1>`, `<tag2>` | <summary> |

> No knowledge matched. (if empty)
```

### Step 3: Analyze Feature Context
1.  Read `context.json` — get `current_feature`.
2.  Read **all available** spec artifacts from `.sdd/spec/<feature-id>/`. The following may exist depending on the feature's design:
    -   `requirements.json` — functional/non-functional requirements and constraints.
    -   `architecture.json` — components, data flow, architectural decisions.
    -   `object_design.json` — design units (classes, components, modules, hooks, handlers, etc.), relationships.
    -   `data_model.json` — data entity schemas and storage definitions (if applicable).
    -   `openapi.yaml` — API contract (if applicable).
    -   `interface_contract.json` — non-HTTP interface definitions (if applicable).

### Step 4: Pre-Plan Clarification
Before generating tasks, check for concerns:
- "This feature requires a new data migration / schema change. Which task should handle it?"
- "Found a similar pattern `form-validation` (tags: form, validation, ui). Apply it or customize?"
- "Spec item REQ-003 still has open clarifications. Resolve via `/sdd-design` first?"

Present BLOCKING concerns to user and **STOP**. Wait for user resolution. Skip if no concerns.

### Step 5: Generate Tasks
-   **If Pattern Match Found**:
    -   Load Pattern Task List.
    -   Replace placeholders (e.g., `{{Entity}}` → `User`).
    -   Cross-reference with spec artifacts to ensure all requirements, design units, interfaces, and entities are covered.
    -   Adjust `target_path` to match `project_rules.md` conventions.
    -   Output `tasks.json`.
-   **If No Match**:
    -   Parse ALL available spec artifacts.
    -   Identify the key implementation units from spec artifacts (e.g., components, modules, services, pages, commands — depending on the project type).
    -   Map each design unit from `object_design.json` to a task, ensuring names, signatures, `kind`, and layer placement are preserved in the task description.
    -   Map additional artifacts (`data_model.json`, `openapi.yaml`, `interface_contract.json`) to relevant tasks if they exist.
    -   Verify every functional requirement in `requirements.json` is addressed by at least one task.
    -   Generate `target_path` for each task based on project rules.
    -   Generate fresh `tasks.json`.

### Step 6: Guardrail Validation
After generating tasks, invoke `sdd-guardrails` with context `"plan"`:
-   **Path Convention Check**: Verify each task's `target_path` matches the architecture style.
    -   Validate each task's `target_path` matches the conventions declared in `project_rules.md`.
-   **Rule Compliance**: Ensure task descriptions don't contradict `project_rules.md`.
-   If violations found → fix tasks → re-validate.

### JSON Writing Rule
When writing `tasks.json`, you **MUST use the file writing tools**. All string values MUST have special characters properly escaped (`\"`, `\\`, `\n`, `\t`, control chars). Validate JSON is well-formed before writing to disk. If validation fails, fix escaping issues before saving.

### Step 7: Finalize
1.  Write `tasks.json` to `.sdd/plan/<feature-id>/tasks.json`.
2.  Update `context.json.current_stage` to `"plan-complete"`.

## Output

Generates `.sdd/plan/<feature-id>/tasks.json` containing:
-   **Task Groups**: Logical grouping of tasks.
-   **Dependencies**: Explicit blocking relationships.
-   **Target Paths**: Expected file paths for each task's output.
-   **Estimated Effort**: Based on historical data from similar patterns.

## Post-step: Feedback Capture (MANDATORY)

After presenting the plan to the user, if the user adjusts the generated plan (changes task granularity, reorders tasks, rejects a pattern match):
1.  Apply the requested changes to `tasks.json`.
2.  **Immediately** write a lesson to `.sdd/knowledge/lessons/` capturing:
    -   What was originally planned vs what the user changed.
    -   Why the adjustment was needed.
    -   Tags for future retrieval (feature name, `planning-tasks`, domain keywords).

This is NOT optional. Every user adjustment to the plan MUST be recorded as a lesson.

## Integration

-   **Input**: `context.json`, `project_rules.md`, `.sdd/spec/<feature-id>/*` (`requirements.json`, `architecture.json`, `object_design.json`, `data_model.json`, `openapi.yaml`, `interface_contract.json`), `sdd-knowledge-base`.
-   **Output**: `.sdd/plan/<feature-id>/tasks.json` (consumed by `sdd-implementer`).
-   **Invokes**: `sdd-guardrails` (plan-level checks).