design git:20260930.86c5e44A

Immutable. This exact content never changes and is served at /api/v1/blob/ca5d89f0d5b13d53.

---
name: design
description: |
  Use in pre-implementation (idea-to-design) stages to understand spec/requirements and create a correct implementation plan before writing actual code.
  Turns ideas into a fully-formed PRD/design/specification and implementation-plan. Creates design docs and task lists in docs/feat/wip/.
---
<!-- codex: tool-name mapping applied. See .codex/scripts/session-start.sh -->

# Task Analysis Process

**Goal: Before writing any code, make sure you understand the requirements and have an implementation plan ready.**

## Conventions

- **Read capy knowledge base conventions** at [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md).
- **Read profile detection** at [shared-profile-detection.md](shared-profile-detection.md). When an active profile contributes a `design/` subdirectory (e.g., `../../profiles/k8s/design/`), its `questions.md` feeds the idea-refinement question pool and its `sections.md` lists required sections the design document must cover. Both the idea-to-design and continue-WIP flows consult the shared procedure; see each flow's workflow file for the specific integration points.

For fresh ideas, two reference files provide methodology and evaluation rubric: [frameworks.md](./frameworks.md) (ideation lenses for the diverge phase) and [refinement-criteria.md](./refinement-criteria.md) (evaluation dimensions and MVP scoping for the converge phase). These are loaded during the instruction-load step and consumed by idea-process.md Step 3 sub-phases.

## Workflow

**Mandatory order — understanding before engagement.** The flow below is strictly sequential. Do not engage with idea prose beyond a keyword scan, read WIP document content, ask refinement questions, or write design content until all instructions — this SKILL.md, the relevant process file, the shared protocols, every resolved profile's `design/` content, and the fresh-idea references below (when applicable) — are fully loaded. Bounded signal inspection for profile detection is the only content-read exception.

The `$kk:design` skill has two entry points; each has its own process file with a detailed workflow. Both follow the same mandatory ordering:

1. **Keyword scan only.** The idea prose (or WIP feature directory) is scanned at the keyword/filename level — enough to drive profile detection, not enough to engage with the content.
2. **Load instructions.** Read the relevant process file ([idea-process.md](./idea-process.md) or [existing-task-process.md](./existing-task-process.md)), the shared protocols above and [example-tasks.md](./example-tasks.md) (task format), even on an unchanged resume.
  - For WIP, also load the drafting guidelines in idea-process.md for potential refinement, without running its fresh-idea sub-phases.
  - For fresh ideas, also read [frameworks.md](./frameworks.md) (ideation lenses) and [refinement-criteria.md](./refinement-criteria.md) (evaluation rubric).
3. **Detect active profiles.** Delegate to [shared-profile-detection.md](shared-profile-detection.md). For fresh ideas, this uses the design interaction pattern (token matching against idea prose). For WIP features, this uses file-based detection with design-pattern fallback.
4. **Load profile content.** For each active profile contributing a `design/` subdirectory, read its `index.md` and all always-load and matching conditional entries. These feed the refinement question pool and required design sections.
5. **Engage with subject matter.** Follow the selected process file's content-reading, refinement and drafting steps.
6. **Recommend next steps.** After drafting or substantive refinement, suggest an optional `$kk:clarify-docs` invocation naming the created or materially revised documents, before the `$kk:review-design` recommendation. An unchanged resume skips the clarification suggestion. Follow the selected process file for review recommendation and implementation handoff.

Clarification is a separate user-selected editing workflow: this skill neither loads its procedure nor runs it automatically. Drafting still owns clear explanations and preservation of required sections, profile topics, decisions, task state and links. A clarification suggestion does not replace design review; neither recommendation executes a review or establishes independent verification.

## Ideas and Prototypes

_Use this for ideas that are not fully thought out and do not have a fully-formed design/specification and/or implementation-plan._

**For example:** I've got an idea I want to talk through with you before we proceed with the implementation.

**Your job:** Help me turn it into a fully formed design, spec, implementation plan, and task list.

See [idea-process.md](./idea-process.md).

## Continue WIP Feature

_Use this to resume work on a feature that already has design docs and a task list in `/docs/feat/wip/`._

**For example:** Let's continue working on the auth system.

**Your job:** Review the current state of the feature, understand what's been done and what's next, then proceed with implementation.

See [existing-task-process.md](./existing-task-process.md).