Kanban Phase 1 — Brainstorm (Human + Agent)

Arguments: <context> <feature_name>.

The user's idea is at its coarsest here. Your job is to convert a rough idea into a precise, testable requirement with FR-### anchors — everything downstream (UC, TC, traceability) hangs off them.

Brainstorming is divergence then convergence: first open the problem up from every useful angle (ideas, users, edge cases, alternatives), then shut it down into a bounded, agreed requirement. Do not rush. The quality of Phase 1 decides how many questions the rest of the pipeline has to re-ask.

Run via orchestrator: normally invoked by kanban-flow. Call this skill directly when a feature is (or should be) at the brainstorm stage.

1. Understand the challenge

Orientation before ideation. Cheap questions here prevent expensive ones later.

Read the repository. Structure, stack, tooling, data model, conventions. Reading code beats asking — never make the user explain what the code already answers.
Read one similar existing feature (if any) for house patterns.
Restate the challenge. In one or two sentences, play the user's idea back: "You want X in order to achieve Y, in the context of Z — is that right?". Fix misunderstandings before generating ideas against the wrong target.
If no .works/ → kf init --defaults (full bootstrap without prompts: config, seeded .kf overrides, .gitignore).

Rules of engagement:

Material ambiguity (missing scope, unclear behavior, conflicting acceptance criteria) → ask up to 3 focused questions, then proceed. Each question names the decision it feeds.
Minor details → make a reasonable assumption and record it in the spec under Assumptions.
The user is the brief, not the implementer. Do not trouble them with mechanics.

2. Diverge — open the problem (framework phase)

A kanban launch can arrive with the idea fully formed or as a vague half-thought. If the requirement is not already crystal clear, run a brainstorming framework to widen the view before committing to a shape.

Pick the framework that fits the situation. Ask yourself (or the user, if genuinely uncertain) which angle is weak:

Angle you need	Framework
Challenge the premise / rebuild from fundamentals	First Principles
Improve / stretch an existing product or flow	SCAMPER
User-centric problem shaping	Design Thinking
New product / new market / launch narrative	Working Backwards
Diagnose why something is broken	5 Whys
Break a creative block / surface many options fast	Rapid Fire

When ambiguity warrants divergence, run one suitable framework and record the outcome in the spec. For an already precise requirement, proceed to authoring and confirmation.

Framework 1: First Principles Thinking

Identify the problem — what are we actually trying to solve?
Break it down — the fundamental truths/components that cannot be argued away.
Question assumptions — for every "we need X", ask do we really? what if we....
Rebuild — if we started fresh with the truths as the only constraint, what would we build?

PROBLEM: [challenge]

CURRENT APPROACH:
- How it's typically done: ...
- Assumptions baked in: ...

FUNDAMENTAL TRUTHS:
1. [core requirement that cannot change]
2. [physical/logical constraint]
3. [user need at the deepest level]

QUESTIONED ASSUMPTIONS:
- "We need X" -> Do we really? What if...?
- "It must be Y" -> Why? Alternative...?

REBUILT SOLUTION:
- [the shape that survives]

WHAT CHANGES IN THE SPEC:
- Scope in / out decisions this surfed (only if it genuinely informs the requirement)

Framework 2: SCAMPER

Apply each lens to the feature. Generate at least one idea per letter.

CHALLENGE: [feature/flow being designed]

[S] Substitute — other tech/approach/component?
[C] Combine — which features/systems can merge?
[A] Adapt — what's similar elsewhere, what can we copy across domains?
[M] Modify — bigger/smaller/faster/slower? exaggerate what?
[P] Put to other uses — who else could use this, for what?
[E] Eliminate — what can be removed without killing the value?
[R] Reverse — opposite ordering, roles, or flow?

TOP 3 IDEAS:
1. ... (why)
2. ... (why)
3. ... (why)

WHICH ONES LAND IN THE SPEC:
- [idea] -> FR/orientation; [idea] -> explicitly out of scope (recorded)

Framework 3: Design Thinking

Empathize — who is the user, what is their current journey, what do they really need (not just what they say)?
Define — problem statement in the form: "[User] needs [need] because [insight]".
Ideate — 10+ ideas, no judgment, quantity first, build on each other.
Prototype — the cheapest thing that validates the direction.
Test — what feedback do we need, what metric proves it works?

EMPATHIZE:
- User: [who]
- Pain points: [...]
- Current journey: [steps]

DEFINE:
- Problem statement: [user] needs [need] because [insight]
- How Might We: [question]

IDEATE (10+):
1..10+

PROTOTYPE:
- MVP concept: ...
- Cheapest validation: ...

TEST:
- Success metric: ...
- Feedback needed: ...

Framework 4: Working Backwards (Amazon-style)

Start from the end experience and work back to what we must build.

Press release — announce the finished feature.
FAQ — answer the customer + internal questions.
Customer experience — the detailed user journey.
Work back to requirements — what must exist for that journey.

PRESS RELEASE:
- Headline: [name] helps [user] [benefit]
- Problem: [2-3 sentences]
- Solution: [2-3 sentences]
- How it works: [plain explanation]

FAQ:
- Q(A): what is it / how different / how to start / cost

REQUIREMENTS THAT MUST EXIST:
1. ... 2. ... 3. ...

Framework 5: 5 Whys

Use when the feature exists to fix a problem whose true cause is unclear. Iterate "why" until the root cause surfaces (5 is the rule of thumb; stop early if a real cause appears).

PROBLEM: [initial symptom]

Why #1 -> Because: ...
Why #2 -> Because: ...
Why #3 -> Because: ...
Why #4 -> Because: ...
Why #5 -> Because: [root cause]

ROOT CAUSE: [summary]

WHAT THE FEATURE MUST ACTUALLY DO: [solution targeting the root cause, not the symptom]

Framework 6: Rapid Fire

Generate 15+ options in one pass, no filtering during generation.

CHALLENGE: [feature]

IDEAS (15+):
1..15+

CATEGORIES:
- Quick wins / Big bets / Experiments / Parking lot

TOP 3 TO PURSUE:
1. ... (why)
2. ... (why)
3. ... (why)

Synthesis (always, whichever framework)

End divergence by answering three questions in the spec's language:

IDEAS SURFACED: [what changed the shape]
SCOPE DECISION: [what's in, what's explicitly out — and why]
REMAINING BLIND SPOTS: [what we could not evaluate cheaply at Phase 1]

3. Create the feature

Check kf list --json first. If the feature already exists, resume its requirement; do not run kf new again. Feature and context names use letters, digits, hyphens or underscores and start with a letter or digit.

Pick the context before you run kf new. A project may declare the contexts it uses in .kf/config.json, and kf new refuses anything outside that list:

kf contexts --json   # declared: [...], restricted: true|false

restricted: true — use one of the declared names, spelled exactly. Auth is refused next to auth, because accepting both is how a second docs tree appears.
restricted: false — nothing is declared; any valid name works, and the brief field tells you how to propose a list. Proposing one is a suggestion for the human to confirm, never something to write into the config yourself.

If kf new refuses the name, it prints the nearest declared one. Take that suggestion or ask the human — do not invent a new context to get past the refusal, and do not add one to .kf/config.json.

kf new {feature_name} --context {context}

Scaffolds .works/brainstorm/{feature}_{ts}/ + metadata + seeded phase-1-spec-requirement.md.

4. Author the requirement

Print the template and instructions:

kf instruct spec-requirement --change {feature_name}

Fill every section of phase-1-spec-requirement.md. Mapping from divergence to sections:

Objective / Problem Statement — the restated challenge (sharpened by the framework).
Scope (in & out) — the SCOPE DECISION from synthesis. Explicit "out" items are valuable: they stop Phase 2-3 from drifting.
Affected surfaces — every user-facing surface the change touches (README, docs site, landing page, CLI -h, examples, changelog, packaging, API reference), one bullet each, or the literal N/A. The spec cannot leave brainstorm without it. Ask the human when the surface list is ambiguous — they own what counts as user-facing.
Functional Requirements FR-### — the traceability anchor. One behavior per FR, phrased so a test could pass/fail on it. Include the priority (must/should/could) and a note carrying any framework rationale.
Non-Functional Requirements — performance, security, UX, accessibility, compliance.
Main Use Cases — one line each with UC-### ids (full narratives live in Phase 2).
Constraints / Assumptions / Edge Cases / Open Questions — edge cases should feel adversarial: empty states, concurrency, permissions, partial failure, boundary values.
Test Strategy — onboard the user on how deep to test (this locks what Phase 2 must produce):
- Ask: "How far do you want this feature tested?" with concrete options:
  - unit — unit tests only, for logic and state. The default for a pure backend or utility feature.
  - unit+integration — unit tests plus tests where the change meets another system, the database or an API. The default for an API or a datastore.
  - full — unit, integration and UI/E2E (Playwright, Cypress, Detox and so on). The default for anything with a user interface or a critical flow, such as a web todo list, a login or a checkout.
- When the user picks full, ask how wide the UI coverage goes: "UI tests for every flow, or only the critical ones?" → {test_level}: full, {ui_test_scope}: critical|all.
- Record it in the spec under the labels that template actually uses: Level in the feature template, Test Level in the bug template, plus UI Tests, Tools (the framework name and the file that runs it) and Coverage Target (80% by default).
- Let the nature of the feature set the default. Do not ask again when the answer is obvious: a CRUD API is unit+integration, an app with a UI is full. Ask only when you genuinely cannot decide.
Acceptance Criteria — each [ ] must be independently verifiable by a human or a test. Under full, at least one criterion per FR must read as a UI action: what is clicked, what is typed, what appears on screen.

Set status: pending → status: confirmed in the spec frontmatter when the human signs off (Phase 1 ends on this confirmation).

Mirror the requirement to docs/requirement/{context}/{feature_name}.md (canonical, human-readable; create the context dir if missing — kf archive refreshes it later).

kf status --change {feature_name}

The checklist reports content completion; human confirmation is still required before advancing.

5. Confirm with the human

Present a tight summary (do not dump the whole file):

FEATURE: {name}  ({context})
STATUS: pending

OBJECTIVE: {one line}

FR SUMMARY:
- FR-001 | must | {behavior}
- ...
UC SUMMARY:
- UC-001 {name}
- ...

ACCEPTANCE (sample):
- [ ] {criterion}

DECISIONS RECORDED:
- {scope decision / assumption}
- ...

SCOPE OUT (explicit):
- {item} — because {reason}

Please confirm the requirement.

On confirmation → set status: confirmed, mirror canonical requirement, run kf stage {feature_name} planning, then load kanban-plan.
If the user pushes back → update the spec, re-confirm. This is normal; the spec exists to absorb disagreement cheaply here, not in implementation.

Done

The requirement is confirmed and mirrored. Hand off to Phase 2 — Planning:

Load the kanban-plan skill and write the four plan artifacts (implementation-plan, use-case-specification, use-case-diagram, test-cases). The one-line use-case summaries and the FR/UC ids from phase-1-spec-requirement.md are the input — the full narratives are written in Phase 2, not carried over from Phase 1. Do not re-derive the ids from scratch.

kanban-brainstorm

SKILL.mdskills/kanban-brainstorm/SKILL.md