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 kf:flow. Call this skill directly when a feature is (or should be) at the brainstorm stage.

0. Classify the path, and say it out loud

kf:flow names a path before this skill runs; if you were called directly, name it now — "this looks bounded, so the spec will be a page and I skip the divergence framework" — so the user can override it:

• Spike — a question or a one-shot operation that lands no code. Stop here: no kf new. Hand off to Skill(kf:spike), which owns the procedure. If the answer becomes work, classify again.
• Bounded — a change to a flow that already exists in this repository. Run sections 1, 3, 4 and 5; skip section 2 (the frameworks). The spec is a page: the restated journey, one or two FRs, the Affected surfaces, a Test Strategy, acceptance criteria. Its Scope comes from the restated journey and the user's answers, since there is no synthesis. Every gate below still applies.
• Architectural — everything else. All sections.

One-way ratchet: if the bounded spec grows a second surface or a new subsystem mid-way, say so and step up to architectural; never the reverse.

1. Understand the challenge

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

1. Read the repository. Structure, stack, tooling, data model, conventions. Reading code beats asking — never make the user explain what the code already answers.
2. Ground the request. Before your first question, verify every entity the idea names against its real definition — the file, command, table, field, endpoint or config key — spelled as the source spells it. A name the user used that the code does not have is your first question, not an assumption. Field-level detail waits for planning; here the names must be real.
3. Read one similar existing feature (if any) for house patterns. Research before you ask. When the idea names an external library, API, service or standard that the repository does not define, or asks how other tools do something (prior art), dispatch Agent(kf:researcher) with ${CLAUDE_PLUGIN_ROOT}/skills/flow/references/researcher-brief.md (mode web or prior-art) before asking the user any question. Do not ask the user first and do not wait for a go-ahead: research triggers on need. The item does not exist yet, so the report goes to the brief's no-item location ($CLAUDE_JOB_DIR/tmp, else the OS temp dir); after kf new in section 3, copy it to <item>/reviews/research-<slug>.md, and cite each report in the spec under Assumptions or Open Questions. Without a web tool the researcher replies BLOCKED: say so in Open Questions instead of answering from memory.
4. 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. Describe the real user journey — what they see and type — and have the user agree to it before any FR list or structural naming; the human decides whether the journey is right, and a spec written before that agreement is rework waiting to happen.
5. 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)

Architectural path only — a bounded change skips this section. 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:

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

1. Identify the problem — what are we actually trying to solve?
2. Break it down — the fundamental truths/components that cannot be argued away.
3. Question assumptions — for every "we need X", ask do we really? what if we....
4. 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

1. Empathize — who is the user, what is their current journey, what do they really need (not just what they say)?
2. Define — problem statement in the form: "[User] needs [need] because [insight]".
3. Ideate — 10+ ideas, no judgment, quantity first, build on each other.
4. Prototype — the cheapest thing that validates the direction.
5. 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.

1. Press release — announce the finished feature.
2. FAQ — answer the customer + internal questions.
3. Customer experience — the detailed user journey.
4. 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. Show the proposal to the human; once they confirm it, write only the list they confirmed to .kf/config.json as "contexts" (the first entry is the default). Never write a list they have not confirmed. The edit dirties the checkout and makes kf stage skip its base fast-forward, so ask the human to commit it before the stage move.

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 on your own.

kf new {feature_name} --context {context}

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

Copy any research report saved earlier to <item>/reviews/research-<slug>.md now, before the spec cites it.

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; on the bounded path, the restated journey and the user's answers. 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. Each bullet is the bare surface name (README.md, not README.md — new flag): kf validate matches it as a lowercase substring of the plan. 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: the feature template has Level, UI Tests, Tools (the framework name and the file that runs it) and Coverage Target (80% by default); the bug template has Test Level, Tools and Coverage Target, and no UI Tests.
  • 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). Write nothing under docs/ here: the close writes the canonical requirement, and a file in the main checkout would make kf stage … planning skip its base fast-forward.

kf status --change {feature_name}

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

5. Review the spec, then confirm with the human

Self-review first, with fresh eyes: placeholders or vague requirements; sections that contradict each other; a scope too wide for one implementation plan; a requirement that could be read two ways. Fix inline.

Then dispatch Agent(kf:spec-reviewer) once, model: opus, with a fresh context: the brief names the work item folder, carries a verbatim excerpt of the user's original request (in the brief or a file you write under the item folder; never only the Objective), names the git ref to ground names against and names a report file (<item>/reviews/spec-review.md). It reports only requirement gaps, untestable FRs or acceptance criteria, internal contradictions and ungrounded names — never new scope. Print spec review ran on: <its model line>; with no report, print spec review: no report. HIGH findings go into the confirmation ask below; the review never blocks on its own, the human does. When the runtime has no subagent tool, run the same four checks yourself and say so.

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}

SPEC REVIEW (spec-reviewer, <model>): {n HIGH, n MEDIUM, n LOW}
- [HIGH] {finding} — {fixed | left for your call because ...}

Please confirm the requirement.

• On confirmation → set status: confirmed, run kf stage {feature_name} planning, then load kf: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. Hand off to Phase 2 — Planning:

Load the kf: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.