# Tasks: JWT Authentication System

> Design: [./design.md](./design.md)
> Implementation: [./implementation.md](./implementation.md)
> Status: in-progress
> Created: 2026-03-11
> Not Doing: OAuth/social login, API rate limiting, token revocation list

## Task 1: User login end-to-end
- **Status:** done
- **Depends on:** —
- **Size:** M
- **Can run in parallel with:** Task 2
- **Docs:** [implementation.md#user-login](./implementation.md#user-login)

### Subtasks
- [x] 1.1 Create `internal/auth/token.go` with `GenerateToken(userID, role)` and `ValidateToken(tokenString)` — access token generation with configurable expiry via `internal/config/auth.go`
- [x] 1.2 Create `POST /api/v1/auth/login` endpoint — accept email/password, verify against user store, return access + refresh tokens
- [x] 1.3 Create `internal/middleware/auth.go` — extract token from `Authorization: Bearer <token>` header, validate via token library, inject user claims into request context. Wire to `/api/v1/auth/login` route in `cmd/server/routes.go`
- [x] 1.4 Integration tests for the login flow: valid credentials → tokens returned, invalid credentials → 401, malformed token → 401, expired token → 401

## Task 2: Token refresh end-to-end
- **Status:** in-progress
- **Depends on:** —
- **Size:** S
- **Can run in parallel with:** Task 1
- **Docs:** [implementation.md#token-refresh](./implementation.md#token-refresh)

### Subtasks
- [x] 2.1 Create `POST /api/v1/auth/refresh` endpoint — accept refresh token, validate, return new access token with rotation
- [ ] 2.2 Integration tests: valid refresh → new access token, expired refresh → 401, reused refresh token → 401

## Task 3: Protected routes end-to-end
- **Status:** pending
- **Depends on:** Task 1
- **Size:** M
- **Can run in parallel with:** —
- **Docs:** [implementation.md#protected-routes](./implementation.md#protected-routes)

### Subtasks
- [ ] 3.1 Apply auth middleware to all `/api/v1/*` routes except `/api/v1/auth/login` and `/api/v1/auth/refresh` in `cmd/server/routes.go`
- [ ] 3.2 Rejection tests: request without token → 401, expired token → 401, valid token → passes through with claims in context
- [ ] 3.3 Verify existing endpoint tests still pass with auth middleware applied

## Task 4: Password hashing migration
- **Status:** blocked
- **Depends on:** —
- **Size:** M
- **Can run in parallel with:** Task 1, Task 2
- **Docs:** [design.md#password-storage](./design.md#password-storage)
- **Blocked:** Waiting on DB migration tooling decision (see design.md#open-questions)

### Subtasks
- [ ] 4.1 Add bcrypt hashing to `internal/auth/password.go` with cost factor from config
- [ ] 4.2 Create migration to add `password_hash` column to users table
- [ ] 4.3 Update user registration flow to hash passwords on create
- [ ] 4.4 Tests: registration stores hashed password, login verifies against hash

## Task 5: Final verification
- **Status:** pending
- **Depends on:** Task 1, Task 2, Task 3, Task 4
- **Size:** S
- **Can run in parallel with:** —

### Subtasks
- [ ] 5.1 Run `$kk:test` skill to verify all tasks — full test suite, integration tests, edge cases
- [ ] 5.2 Run `$kk:document` skill to update any relevant docs
- [ ] 5.3 Run `$kk:review-code` skill with the project language input to review the implementation
- [ ] 5.4 Run `$kk:review-spec` skill to verify implementation matches design and implementation docs

## Dependency Graph

```
Task 1 ─→ Task 3 ─→ Task 5
Task 2 ─────────────→ Task 5
Task 4 (blocked) ────→ Task 5
```

### Workflow: Continue WIP Feature

1. **Find the feature** — Locate the feature directory in `/docs/feat/wip/`. If multiple WIP features exist, ask the user which one to work on.

2. **Review progress** — Read `tasks.md` to understand:
   - Which tasks are done, in-progress, or pending
   - What dependencies exist between remaining tasks
   - Any notes logged on previous subtasks

3. **Review context** — Read the linked `design.md` and `implementation.md` to understand the full picture. Also check any relevant contributing guidelines and documentation. **Capy search:** Search `kk:arch-decisions` and `kk:project-conventions` for context relevant to the feature being resumed.

4. **Detect active profiles** — Apply [shared-profile-detection.md](shared-profile-detection.md). Unlike the fresh-idea flow, the feature directory's files ARE available: feed the full feature-directory file list (and any in-tree artifacts the feature has produced so far) to the shared procedure's file-based input model. If the file list yields no profile — common when the design is for future work that has not emitted profile-bearing artifacts yet — fall back to the [design interaction pattern](shared-profile-detection.md#the-design-interaction-pattern) against the `design.md` prose; it iterates all profiles with `## Design signals` and handles token matching + confirmation. For each active profile, use the `Read` tool on `../../profiles/<name>/design/index.md`; skip silently if absent. Load every always-load entry; the profile's `questions.md` guides any further refinement and its `sections.md` lists required sections the design document must cover. A design authored before the profile rubric existed should be audited against `sections.md` on resumption.

5. **Assess readiness:**
   - **If tasks are well-documented and clear** → proceed to implement using the `$kk:implement` skill.
   - **If tasks need refinement** (missing details, unclear subtasks, gaps in the plan) → update `tasks.md` and/or the design/implementation docs before proceeding. Follow the documentation guidelines from the [Ideas and Prototypes](#ideas-and-prototypes) section.

<!-- Adapted from addyosmani/agent-skills (MIT License, Copyright Addy Osmani)
     Source: https://github.com/addyosmani/agent-skills/blob/539a78574773fe7e46cf8bbf9c67bcc9db63c335/skills/idea-refine/frameworks.md
     Pinned at: 539a78574773fe7e46cf8bbf9c67bcc9db63c335 -->

# Ideation Frameworks Reference

These frameworks apply to software engineering features — APIs, infrastructure, developer tools, internal systems, library design. The goal is to unlock thinking about implementation approaches and architectural trade-offs, not to follow a checklist. Pick the lens that fits the idea; don't mechanically run every framework.

## SCAMPER

A structured way to transform an existing idea by applying seven different operations:

- **Substitute:** What component, technology, or process could you swap out? What if you replaced the synchronous RPC with an event-driven approach? The relational database with a document store? The monolith deployment with a service mesh?
- **Combine:** What if you merged this with another product, service, or idea? What two things that don't usually go together would create something new?
- **Adapt:** What else is like this? What ideas from other domains or systems could you borrow? What parallel exists in nature?
- **Modify (Magnify/Minimize):** What if you made it 10x bigger? 10x smaller? What if you exaggerated one feature? What if you stripped it to the absolute minimum?
- **Put to other uses:** Who else could use this? What other problems could it solve? What happens if you use it in a completely different context?
- **Eliminate:** What happens if you remove a feature entirely? What's the version with zero configuration? What would it look like with half the steps?
- **Reverse/Rearrange:** What if you did the steps in the opposite order? What if the user/client did the work instead of the system/server (or vice versa)? What if you reversed the dependency direction, or the value chain?

**Best for:** Improving or reimagining existing systems/products/features. Less useful for greenfield ideas.

## How Might We (HMW)

Reframe problems as opportunities using the "How Might We..." format:

- Start with an observation or pain point
- Reframe it as "How might we [desired outcome] for [specific user] without [key constraint]?"
- Generate multiple HMW framings of the same problem — different framings unlock different solutions

**Good HMW qualities:**
- Narrow enough to be actionable ("...help new users find relevant content in their first 5 minutes")
- Broad enough to allow creative solutions (not "...add a recommendation sidebar")
- Contains a tension or constraint that forces creativity

**Bad HMW qualities:**
- Too broad: "How might we make users happy?"
- Too narrow: "How might we add a button to the settings page?"
- Solution-embedded: "How might we build a chatbot for support?"

**Best for:** Reframing stuck thinking. When someone is anchored on a solution, pull them back to the problem.

## First Principles Thinking

Break the idea down to its fundamental truths, then rebuild from there:

1. **What do we know is true?** (not assumed, not conventional — actually true)
2. **What are we assuming?** List every assumption, even the ones that feel obvious
3. **Which assumptions can we challenge?** For each, ask: "Is this actually a law of physics, or just how it's been done?"
4. **Rebuild from the truths.** If you only had the fundamental truths, what would you build?

**Best for:** Breaking out of incremental thinking. When every idea feels like a small improvement on the status quo.

## Jobs to Be Done (JTBD)

Focus on what the user is trying to accomplish, not what they say they want:

- **Functional job:** What task are they trying to complete?
- **Emotional job:** How do they want to feel?
- **Social job:** How do they want to be perceived?

Format: "When I [situation], I want to [motivation], so I can [expected outcome]."

**Key insight:** Users don't adopt tools — they hire them to do a job. The competing solution isn't always in the same category. (A CLI tool competes with a shell script alias, not just other CLI tools.)

**Best for:** Understanding the real problem. When you're not sure if you're solving the right thing.

## Constraint Mapping

Deliberately impose constraints to force creative solutions:

- **Time constraint:** "What if you only had 1 day to build this?"
- **Feature constraint:** "What if it could only have one feature?"
- **Tech constraint:** "What if you couldn't use [the obvious technology]?"
- **Cost constraint:** "What if it had to be free forever?"
- **Audience constraint:** "What if your user had never used a computer before?"
- **Scale constraint:** "What if it needed to work for 1 billion users? What about just 10?"

**Best for:** Cutting through complexity. When the idea is growing too large or too vague.

## Pre-mortem

Imagine the idea has already failed. Work backwards:

1. It's 12 months from now. The project shipped and flopped. What went wrong?
2. List every plausible reason for failure — technical, adoption, integration, operational
3. For each failure mode: Is this preventable? Is this a signal the idea needs to change?
4. Which failure modes are you willing to accept? Which ones would kill the project?

**Best for:** Phase 2 evaluation. Stress-testing ideas that feel good but haven't been pressure-tested.

## Analogous Inspiration

Look at how other domains solved similar problems:

- What industry or system has already solved a version of this problem?
- What would this look like if someone else built it?
- What natural system or distributed system works this way?
- What historical precedent exists?

The key is finding *structural* similarities, not surface-level ones. "Git for config files" is surface-level. "A content-addressable store with branching semantics that solves the concurrent-edit problem" is structural.

**Best for:** Phase 1 expansion. Generating variations that feel genuinely different from the obvious approach.

### Workflow

Copy this checklist and check off items as you complete them:

```
Task Progress:
- [ ] Step 1: Understand the current state of the project
- [ ] Step 2: Check the documentation
- [ ] Step 3: Refine the idea
- [ ] Step 4: Describe the design
- [ ] Step 5: Document the design
- [ ] Step 6: Create the task list
```

**Step 1: Understand the current state of the project**

To properly refine the idea into a fully-formed design you need to **understand the existing code** in our working directory to know where we're starting off.

**Step 2: Check the documentation**

In order to gain a better understanding of the project, **check the contributing guidelines and any relevant documentation**. For example, take a look at `CONTRIBUTING.md` and `docs` directory.

**Capy search:** Before refining the idea, search `kk:arch-decisions` and `kk:project-conventions` for prior design context related to the feature area being discussed.

**Step 3: Refine the idea**

**Detect active profiles before refining.** The design phase runs before any code exists, so file-based detection is impossible. Run the design interaction pattern from [shared-profile-detection.md §The `$kk:design` interaction pattern](shared-profile-detection.md) — it iterates all profiles with `## Design signals`, matches their declared tokens against the idea prose, and handles confirmation prompts. Never auto-activate a profile silently.

For each active profile, use the `Read` tool on `../../profiles/<name>/design/index.md`. Surface and skip if absent; not every profile populates a `design/` subdirectory. Load every file listed under **Always load**; a profile's `questions.md` (when present) seeds the refinement question pool. Integrate the profile's questions into the sub-phases below — one question per message, as always.

Note: [frameworks.md](frameworks.md) and [refinement-criteria.md](refinement-criteria.md) are already loaded during the mandatory instruction-load phase (SKILL.md step 2). Do not reload them here.

**Interaction style throughout:** one question per message, multiple choice preferred. Open-ended questions are OK too. The sub-phases below add structure to _what_ is asked, not _how_.

**Step 3 Progress:**
- [ ] 3a HMW framing confirmed
- [ ] 3b who/persona confirmed
- [ ] 3b success metric confirmed
- [ ] 3b constraints confirmed
- [ ] 3c complexity classification confirmed
- [ ] 3c alternatives presented
- [ ] 3d direction chosen
- [ ] 3e assumptions, Not Doing, and Rejected Alternatives presented

**3a. Frame the problem.** Restate the idea as a rough "How Might We" problem statement — a directional anchor, not a fully specified template. Use [frameworks.md §HMW](frameworks.md#how-might-we-hmw) for format quality guidance (good vs bad HMW qualities), but do not attempt to fill every slot (specific user, key constraint) yet — those come from 3b. Present the framing to the user for confirmation or correction before proceeding. This anchors all subsequent questions on the problem, not a solution.

**3b. Establish foundations.** Three things must be explicitly answered before advancing to alternatives. Ask one at a time, multiple choice preferred:

1. **Who is this for** — specific user, persona, or role. "Everyone" is not an answer.
2. **What does success look like** — a measurable outcome, not a feature name. "Users can log in" → "Login p99 latency under 500ms with zero-downtime deployment."
3. **Technical/system constraints** — what existing systems, APIs, data stores, infrastructure, or conventions must be respected. What is off-limits to change.

Do not advance to 3c until all three are confirmed.

**3c. Explore alternatives.** Select frameworks from the already-loaded [frameworks.md](frameworks.md) that fit the idea — pick by "Best for" guidance, never run every framework.

Classify the idea before generating alternatives. **Non-trivial** if it involves architectural choices, multiple valid implementation approaches, or significant unknowns. **Simple** if the implementation path is singular and the main decisions are parameter-level. State which classification and why, then confirm with the user:

- **For simple ideas:**
  > "This looks like a straightforward single-path problem — I'll propose the direct approach plus one alternative. Want me to explore more broadly instead?"
- **For non-trivial ideas:**
  > "This has multiple valid approaches with real trade-offs — I'll explore 2-3 alternative directions using [selected frameworks] and summarize their trade-offs. Sound right, or should I narrow the focus?"

Two paths:

- **Non-trivial ideas** (multiple valid approaches, significant unknowns, architectural choices): generate 2-3 alternative directions using selected lenses. Present each with a one-sentence trade-off summary. After presenting alternatives, stop and ask which alternatives to carry into evaluation — or whether to add a missed constraint and loop back. Do not evaluate or recommend a direction in the same message that first presents alternatives unless the user explicitly asks you to continue.
- **Simple ideas** (single-concern, low-uncertainty, obvious path): propose the direct implementation path plus briefly mention one alternative optimized for a different constraint (e.g., "We could also do X if extensibility matters more than simplicity"). Ask which to proceed with.

Never skip this step silently — the user always sees at least two options. If the user rejects all alternatives, ask what constraint or dimension was missed, then loop back to 3c with that input as an additional lens.

**3d. Converge.** Evaluate each direction against the already-loaded [refinement-criteria.md](refinement-criteria.md) (User Value, Feasibility, Differentiation) via criteria-based analysis. Present a pros/cons matrix and recommend one direction with a one-line rationale per rejected alternative.

If alternatives make specific factual claims about APIs, libraries, or existing code, offer the user an explicit choice: "Some of these alternatives make specific technical claims I can fact-check. Want me to run `$kk:chain-of-verification:isolated` to verify them, or should I proceed with the analysis as-is?" Let the user decide — do not auto-invoke or auto-skip CoVe.

**3e. Surface assumptions and scope.** Before moving to Step 4, produce and present to the user:

- **Assumptions** — what is baked into the chosen direction but has not been validated. Each assumption should be specific enough to be testable or falsifiable — not vague hedges like "the API is fast enough."
- **Not Doing** — explicit scope exclusions with a one-line reason each.
- **Rejected Alternatives** — each alternative evaluated in 3d that was not chosen, with a one-line rationale for why it lost. This is the convergence rationale from the pros/cons matrix, persisted so future reviewers can see what was considered and why.

All three become first-class artifacts in the design document (Step 5) and tasks.md header (Step 6 — Not Doing only).

**Step 4: Describe the design**

Once you believe you understand what we're trying to achieve, stop and **describe the whole design** to me, **in sections of 200-300 words at a time**, **asking after each section whether it looks right so far**.

**If the design recommends a specific library, SDK, framework, or API** — especially one not already in use in this project — apply the `$kk:dependency-handling` skill BEFORE committing to that recommendation. Verifying behavior against context7 at design time prevents proposing something that doesn't actually work the way you assumed.

**Step 5: Document the design**

Document in .md files the entire design and write a comprehensive implementation plan.

Feel free to break out the design/implementation documents into multi-part files, if necessary.

**For each active profile** (from Step 3), re-consult `../../profiles/<name>/design/index.md` (using the same resolved plugin-root path you used in Step 3) and apply every always-load entry whose content shapes the final design document. Profile-contributed `sections.md` (when present) names required sections the design document must cover. Do not drop a required section silently; if a section genuinely does not apply, state so explicitly with a one-line justification.

When creating documentation, follow this approach:

- IF this is this a completely new feature - document it in in `/docs/feat/wip/[feature-title]/{design,implementation}.md`.
- ELSE this an improvement or an addition to an existing feature:
  - If the feature is still WIP (documented under `/docs/feat/wip`) - ask the user if you should update the existing design/implementation documents, or create new ones in a sub-directory of the existing feature.
  - Else the feature is completed (documented under root of `/docs`) - create new design/implementation documents in a sub-directory of the existing feature.

**When documenting design and implementation plan**:

- Assume the developer who is going to implement the feature is an experienced and highly-skilled %LANGUAGE% developer, but has zero context for our codebase, and knows almost nothing about our problem domain. Basically - a first-time contributor with a lot of programming experience in %LANGUAGE%.
- **Document everything the developer may need to know**: which files to touch for each task, code structure to be aware of, testing approaches, any potential docs they might need to check. Give them the whole plan as bite-sized tasks.
- **Make sure the plan is unambiguous, detailed and comprehensive** so the developer can adhere to DRY, YAGNI, TDD, atomic/self-contained commits principles when following this plan.
- **Pair each step with an explicit verification.** Every implementation step should name *how the developer will know it worked* — a specific test to run, a command whose output to check, or an observable behavior. Use the form `Step → verify: <check>`. Steps without a verification are a smell: either the step is too vague, or the work isn't really done when the step is.
- **Include an Assumptions section** — carried from Step 3e. List assumptions baked into the design, each specific enough to be validated or invalidated during implementation. Assumptions are not caveats — they are testable bets the design depends on.
- **Include a Not Doing section** — carried from Step 3e. Explicit scope exclusions with a one-line rationale each. These are genuine scope decisions, not deferred work items. If something is deferred (will be done later), say so in the implementation plan, not in Not Doing.
- **Include a Rejected Alternatives section** — carried from Step 3e. Each alternative considered during convergence (3d) that was not chosen, with a one-line rationale for why it was rejected. Serves a different audience than Not Doing: Not Doing tells the implementer what's out of scope; Rejected Alternatives tells a future reviewer why this approach was chosen over others.

But, of course, **DO NOT:**

- **DO NOT add complete code examples**. The documentation should be a guideline that gives the developer all the information they may need when writing the actual code, not copy-paste code chunks.
- **DO NOT add commit message templates** to tasks, that the developer should use when committing the changes.
- **DO NOT add other small, generic details that do not bring value** and/or are not specifically relevant to this particular feature. For example, adding something like "to run tests, execute: 'go test ./...'" to a task does not bring value. Remember, the developer is experienced and skilled!

**Capy index:** After documenting the design, index key architecture decisions and trade-offs as `kk:arch-decisions`. Only index non-obvious rationale — skip if the decisions are self-evident from the docs themselves.

**Step 6: Create the task list**

Based on the implementation plan documented in Step 5, create a `tasks.md` file in the same `/docs/feat/wip/[feature-title]/` directory.

Follow the structure and conventions in the [example task file](./example-tasks.md). Key points:

- **Header metadata** links back to design/implementation docs and tracks overall feature status
- **One H2 per task** with status, dependencies, and a link to the relevant docs section
- **Checkbox subtasks** are concrete, actionable implementation steps — specific enough that a developer with no project context can follow them
- **Subtask descriptions** name the file/function/component being touched and what to do with it — not vague ("implement auth") but precise ("create `internal/auth/token.go` with `GenerateToken` and `ValidateToken` functions")
- **Dependencies** reference other tasks by number when ordering matters
- **Status values:** `pending`, `in-progress`, `done`, `blocked` (with reason)
- Tasks should map roughly 1:1 to atomic, self-contained commits
- **Always include a final verification task** that depends on all other tasks — it should invoke `$kk:test` to run the full test suite, `$kk:document` to update any relevant docs, `$kk:review-code` with project's language input to review the code, and `$kk:review-spec` to verify the implementation matches the design and implementation docs
- **Not Doing in header:** The tasks.md header metadata block includes a `> Not Doing:` line listing the concise scope exclusions from design.md (names only, no extended rationale). The implement skill reads tasks.md first; this puts scope boundaries front and center.
- **Vertical slicing:** Each task delivers one complete, testable user-facing path — not a horizontal layer. Anti-pattern: "Do not create tasks that complete an entire layer (all database work, then all API work, then all UI work) — this defers integration risk to the end." A task like "create all DB models" is wrong; "create user registration end-to-end (model + endpoint + validation + test)" is right.
- **Size tags:** Each task gets a `**Size:** S/M/L` field. S = 1-2 files, M = 3-5 files, L = 5+ files. Size measures complexity, not raw file count — exclude boilerplate registrations, test fixtures, and config entries that are mechanical consequences of the main change. Hard rule: any task tagged L is forbidden as a single task. Break it into smaller vertical slices.
- **Slicing strategies:** Three strategies, noted per-task only when deviating from default:
  - **Vertical** (default): each task delivers one complete path from input to output, testable in isolation.
  - **Contract-First**: define the interface/API boundary first, then implement each side independently. Use when introducing a new external boundary (API, SDK, message queue).
  - **Risk-First**: tackle the most uncertain piece first to surface unknowns early. Use when one task carries significantly more uncertainty than others.
- **Parallel markers:** Each task gets a `**Can run in parallel with:**` field listing task numbers with no blocking dependency, or `—`.
- **Dependency graph:** After all tasks, add a `## Dependency Graph` section with an ASCII diagram showing task relationships. Written once, never updated during implementation.

At the end of Step 6, recommend invoking `$kk:review-design <feature>` as the post-design gate. The default scope reviews all documents (`design.md + implementation.md + tasks.md`), including the task-format checks.

<!-- Adapted from addyosmani/agent-skills (MIT License, Copyright Addy Osmani)
     Source: https://github.com/addyosmani/agent-skills/blob/539a78574773fe7e46cf8bbf9c67bcc9db63c335/skills/idea-refine/refinement-criteria.md
     Pinned at: 539a78574773fe7e46cf8bbf9c67bcc9db63c335 -->

# Refinement & Evaluation Criteria

Use this rubric to stress-test idea directions during convergence. These criteria apply to software engineering features — APIs, infrastructure, developer tools, internal systems, library design. Not every criterion applies to every idea — use judgment about which dimensions matter most for the specific context.

## Core Evaluation Dimensions

### 1. User Value

The most important dimension. If the value isn't clear, nothing else matters.

**Painkiller vs. Vitamin:**

- **Painkiller:** Solves an acute, frequent problem. Users will actively seek this out. They'll switch from their current solution. Signs: people describe the problem with emotion, they've built workarounds, they'll pay for a solution.
- **Vitamin:** Nice to have. Makes something marginally better. Users won't go out of their way. Signs: people nod politely, say "that's cool," then don't change behavior.

**Questions to ask:**

- Can you name 3 specific people who have this problem right now?
- What are they doing today instead? (The real competitor is always the current workaround.)
- Would they switch from their current approach? What would make them switch?
- How often do they encounter this problem? (Daily problems > monthly problems)
- Is this a "pull" problem (users are asking for this) or a "push" problem (you think they should want this)?

**Red flags:**

- "Everyone could use this" — if you can't name a specific user, the value isn't clear
- "It's like X but better" — marginal improvements rarely drive adoption
- The problem is real but rare — high intensity but low frequency rarely justifies a product

### 2. Feasibility

Can you actually build this? Not just technically, but practically.

**Technical feasibility:**

- Does the core technology exist and work reliably?
- What's the hardest technical problem? Is it a known-hard problem or a novel one?
- Are there dependencies on third parties, APIs, or data sources you don't control?
- What's the minimum technical stack needed? (If the answer is "a lot," that's a signal.)

**Resource feasibility:**

- What's the minimum team/effort to build an MVP?
- Does it require specialized expertise you don't have?
- Are there regulatory, legal, or compliance requirements?

**Time-to-value:**

- How quickly can you get something in front of users?
- Is there a version that delivers value in days/weeks, not months?
- What's the critical path? What has to happen first?

**Red flags:**

- "We just need to solve [very hard research problem] first"
- Multiple dependencies that all need to work simultaneously
- MVP still requires months of work — likely not minimal enough

### 3. Differentiation

What makes this genuinely different? Not better — _different_.

**Questions to ask:**

- If a user described this to a friend, what would they say? Is that description compelling?
- What's the one thing this does that nothing else does? (If you can't name one, that's a problem.)
- Is this differentiation durable? Can a competitor copy it in a week?
- Is the difference something users actually care about, or just something builders find interesting?

**Types of differentiation (strongest to weakest):**

1. **New capability:** Does something that was previously impossible
2. **10x improvement:** So much better on a key dimension that it changes behavior
3. **New audience:** Brings an existing capability to people who were excluded
4. **New context:** Works in a situation where existing solutions fail
5. **Better UX:** Same capability, dramatically simpler experience
6. **Cheaper:** Same thing, lower cost (weakest — easily competed away)

**Red flags:**

- Differentiation is entirely about technology, not user experience
- "We're faster/cheaper/prettier" without a structural reason why
- The feature that differentiates is not the feature users care most about

## Assumption Audit

For every idea direction, explicitly list assumptions in three categories:

### Must Be True (Dealbreakers)

Assumptions that, if wrong, kill the idea entirely. These need validation before building.

Example: "The external API supports batch operations" — if it doesn't, the entire design around bulk processing doesn't work.

### Should Be True (Important)

Assumptions that significantly impact success but don't kill the idea. You can adjust the approach if these are wrong.

Example: "Teams will adopt the CLI over the existing manual workflow" — if wrong, you need a different rollout strategy, but the core tool can still work.

### Might Be True (Nice to Have)

Assumptions about secondary features or optimizations. Don't validate these until the core is proven.

Example: "Teams will want to export reports to Slack" — a convenience feature, not a core value proposition.

## Decision Framework

When choosing between directions, rank on this matrix:

|                | High Feasibility | Low Feasibility |
| -------------- | ---------------- | --------------- |
| **High Value** | Do this first    | Worth the risk  |
| **Low Value**  | Only if trivial  | Don't do this   |

Then use differentiation as the tiebreaker between options in the same quadrant.

## MVP Scoping Principles

When defining MVP scope for the chosen direction:

1. **One job, done well.** The MVP should nail exactly one user job. Not three jobs done partially.
2. **The riskiest assumption first.** The MVP's primary purpose is to test the assumption most likely to be wrong.
3. **Time-box, not feature-list.** "What can we build and test in [timeframe]?" is better than "What features do we need?"
4. **The 'Not Doing' list is mandatory.** Explicitly name what you're cutting and why. This prevents scope creep and forces honest prioritization.
5. **If it's not embarrassing, you waited too long.** The first version should feel incomplete to the builder. If it doesn't, you over-built.

# Capy Knowledge Base Protocol

If `capy` MCP tools are not available in this session, skip all search and index steps below and proceed normally.

## Source Label Taxonomy

All plugin-managed labels use the `kk:` namespace prefix.

| Label                    | Contents                                                              |
| ------------------------ | --------------------------------------------------------------------- |
| `kk:arch-decisions`      | Architecture decisions, design rationale, trade-offs                  |
| `kk:review-findings`     | Code review patterns, recurring issues, anti-patterns                 |
| `kk:lang-idioms`         | Language best practices, idiomatic patterns from external sources     |
| `kk:project-conventions` | Discovered project patterns, naming conventions, structural decisions |
| `kk:test-patterns`       | Testing approaches, edge cases, test infrastructure decisions         |
| `kk:debug-context`       | Root causes, tricky bugs and their fixes, environment gotchas         |

## Search Conventions

- Use 2-4 specific terms per query — not vague keywords
- Always scope with `source` filter to relevant `kk:*` labels
- Use `source: "kk:"` only for broad cross-domain searches (e.g., CoVe verification)
- Default `limit: 3` per query unless more context is needed
- **Cold-start fallback:** If no results, proceed with standard guidelines — empty results are normal for new projects

## Index Conventions

- Only index non-obvious learnings not derivable from reading the code or git history
- Keep content concise — summarize the insight, don't dump raw output
- Always use a `kk:` prefixed label from the taxonomy above
- One concept per `capy_index` call — don't bundle unrelated learnings
- Skip indexing if the insight is already captured in design docs or CLAUDE.md

## Profile detection procedure

Single source of truth for computing the set of profiles active in the current context.
Consumed by six skills: `$kk:review-code`, `$kk:review-spec`, `$kk:design`, `$kk:implement`, `$kk:test`, and `$kk:document`.

Every profile under `klaude-plugin/profiles/<name>/` declares its own trigger rule in `DETECTION.md` using the mandatory three-section schema (`## Path signals`, `## Filename signals`, `## Content signals`).
The shared procedure below applies the same algorithm against every profile's declared values.

### Inputs per consuming skill

Not every consumer has a diff available. Use the input listed for your skill:

- **`$kk:review-code`** — git diff (staged, or an explicit commit range). Scope is
  the set of files the diff touches.
- **`$kk:review-spec`** — git diff when invoked standalone; the feature directory's
  full file list when invoked by `$kk:implement` (spec review runs over the whole
  feature, not just the current task's diff).
- **`$kk:test`** — git diff mid-feature, OR the feature directory's file list
  post-implementation.
- **`$kk:implement`** — the current sub-task's target file list, augmented by the
  diff accumulated so far in the feature.
- **`$kk:design`** — **no file list available** (implementation does not yet exist).
  Detection uses a user-declared or keyword-inferred signal instead; see
  [The `$kk:design` interaction pattern](#the-design-interaction-pattern) below.
- **`$kk:document`** — feature directory's current file list; diff optional.

### The `$kk:design` interaction pattern

The design phase runs before any code exists, so file-based detection is impossible. Detection uses idea-prose keyword matching against tokens declared in each profile's `DETECTION.md`.

**Algorithm:**

1. **Collect tokens.** Iterate §Known profiles. For each `<name>`, `Read` `../../profiles/<name>/DETECTION.md`. If the file has no `## Design signals` section, skip — that profile does not participate in design-phase detection. Otherwise, parse `display_name` and `tokens` from the section.
2. **Build union.** Collect all declared tokens into a single set, each tagged by its source profile name and `display_name`.
3. **Match.** Check the idea prose against the union. Matching is case-insensitive, whole-word (so `pod` in "podcast" does not fire).
4. **Confirm.** On match, surface a confirmation prompt per matched profile:
   *"This appears to be a {display_name} feature. Activate the {profile_name} profile?"* — let the user confirm yes/no. When multiple profiles match, confirm each independently.
5. **Fallback.** If no token matches but the idea is **ambiguous** — names infrastructure, deployment, runtime, or platform concerns without naming a specific technology (e.g., _"add a caching layer for the service"_, _"build a CI pipeline"_, _"deploy to production"_); or includes overloaded tokens that collide across domains — build the fallback prompt dynamically from all profiles that declare `## Design signals`:
   *"Does this feature involve {display_name_1, display_name_2, ...}? If yes, which?"*

Confirmation is required — the $kk:design skill never auto-activates a profile silently. The narrow per-profile token sets avoid noisy false positives from tokens that overload across domains.

Once activated, subsequent design-phase steps treat the profile as active in the same record shape produced by file-based detection (see §Output shape).

### Known profiles

This is the authoritative enumeration of profile `<name>`s — do NOT try discover profiles via any other means.
An explicit list is boring, deterministic, and unambiguous; runtime filesystem enumeration against the plugin tree has proven unreliable.

- `go`
- `python`
- `java`
- `js_ts`
- `kotlin`
- `k8s`
- `k8s-operator`
- `skill-md`

### Algorithm

This procedure reads files under the plugin root. The main agent resolves the plugin root from its shell variable `$TOOLBOX_PLUGIN_ROOT`; a Read-only sub-agent uses the absolute plugin-root path injected into its prompt under `## Plugin Root` (see its agent definition). Substitute that resolved path for the plugin-root prefix in every `…/profiles/…` read below.

1. **Iterate profiles.** For each §Known profiles `<name>`:
   1. Use the `Read` tool on `../../profiles/<name>/DETECTION.md`.
   2. If `Read` fails with ENOENT (profile name in list but directory missing — a stale list entry), skip silently and move on.
   3. If `Read` succeeds, parse the declared `## Path signals`, `## Filename signals`, and `## Content signals` sections.

2. **Evaluate in cost order.** For each input file, check signals in this order: path → filename → content. Cheapest first.
3. **Apply the authority rule.** A file activates the profile only if a **filename signal** OR **content signal** matches.
   A path-only match does NOT activate. Paths are a pre-filter that promotes files to "candidates"; authoritative activation requires filename or content confirmation.
   A file that matches NO path signal is still evaluated against filename and content signals — path pre-filtering is a cost hint, not a gate.
   (Otherwise a `Chart.yaml` at a non-standard path would be missed.)
4. **Bound content inspection.** Read at most ~16 KB per file when evaluating content signals.
   Multi-document YAML is inspected per `---`-separated block — a file may have five blocks, and only the third need match for the file to activate the profile.
5. **Collect records.** Accumulate one record per matched profile with the triggering files and the signal descriptions that fired.

### Tool choice

- Single file at `../../…` → `Read`. This is what the algorithm uses.
- Enumeration across profiles → iterate the §Known profiles list, `Read` each. Never `Glob` (cwd-scoped, misses outside-cwd paths).

### Two dimensions: cost vs authority

Signals live on two axes that point in different directions. Keep them separate in your mental model:

- **Evaluation cost** (cheapest first): path < filename < content.
  Path globs touch only the path string;
  filename matches are exact string compares;
  content inspection opens the file.
- **Authority** (most authoritative first): filename ≈ content > path.
  A filename or content match activates the profile; a path-only match does not.
  Filename and content are equally authoritative, but filename resolves first at runtime — a filename match short-circuits content inspection for that file.

Evaluating cheapest-first optimizes work. Applying authority correctly prevents false positives from incidental path matches — a stray `manifests/` directory in a Go project does not make the project Kubernetes.

### Plugin-root resolution failure

If every `Read` attempt in Algorithm step 1 fails — i.e., the plugin root could not be resolved (the variable is unset for the main agent, or no `## Plugin Root` path was provided to a sub-agent) or the paths do not exist — the procedure cannot continue.

On that failure:

1. Emit an actionable error pointing to `CLAUDE.md` §Profile Conventions.
2. Return an empty result set so the calling skill falls back to generic guidance rather than panicking.
3. Do not retry; do not silently guess a path.

Consumers inherit this check by invoking the shared procedure — no skill re-implements it.

### Output shape

A list of records, one per matched profile:

```
[
  {
    profile: "<name>",                     // directory name under profiles/
    triggered_by: [
      "filename: Chart.yaml",              // signal type + matched value
      "content: apiVersion+kind in block 2"
    ],
    files: [
      "path/to/file1.yaml",
      "path/to/file2.yaml"
    ]
  },
  ...
]
```

Field semantics:

- `profile` — the directory name under `profiles/` (e.g., `go`, `python`, `k8s`).
  Used downstream to resolve `profiles/<profile>/<phase>/index.md`,
  where `<phase>` is the profile phase subdirectory named identically to the calling skill:
  `review-code/`, `review-spec/`, `design/`, `implement/`, `test/`, or `document/`.
- `triggered_by` — which signal type fired and the specific value that matched.
  For debugging and for explaining detection to the user; never used as the key for profile lookup.
- `files` — the subset of input files that activated this profile.
  Skills use this to scope behavior (e.g., `helm lint` runs only on files triggered under Helm filename signals, not on every YAML in the diff).

When no profile matches, return the empty list `[]`. The caller falls back to generic guidance, identical to today's "no language detected" path.

---
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 the idea prose beyond a keyword scan, ask refinement questions, or write design content until all instructions — this SKILL.md, the relevant process file, the shared profile-detection procedure, every resolved profile's `design/` content, and (for fresh ideas) the reference files [frameworks.md](./frameworks.md) and [refinement-criteria.md](./refinement-criteria.md) — are fully loaded.

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)), and (for fresh ideas) the reference files [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 entries (`questions.md`, `sections.md`). These feed the refinement question pool and required design sections.
5. **Engage with subject matter.** Only now: ask refinement questions, analyze the idea, write design content.

## 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).