refactor(brainstorm): flow:brainstorm 독립 skill로 분리#4
Conversation
Extract multi-LLM brainstorming from skills/plan/SKILL.md:52-202 into a
first-class skill that:
- Owns provider lenses, dispatch contract, idempotency check, and
brainstorm.md synthesis template (lifted verbatim from plan).
- Resolves input by precedence: research.md + meta.md, else meta.md only,
else inline task brief with ad-hoc
.planning/<yyyy-mm-dd>-brainstorm-<slug>/ output (mirrors the
existing pr<N>-review variant).
- Carries triggering keywords ("brainstorm", "options", "alternatives",
"다각도", "second opinion before planning") in the frontmatter
description for Claude Code auto-invocation.
flow:plan and flow:research will be trimmed to short pointers in
follow-up commits. Resolves the "Future refactor (open question)" note
at skills/plan/SKILL.md:200-202.
Collapse the inline "Multi-LLM brainstorming" section (formerly ~150 lines) to a ~40-line "Optional brainstorming sub-phase" pointer: - Keep the size-based trigger matrix (S skip / M conditional / L always), the cross-module / security-sensitive / public-surface flags, and the "ask once when unsure" rule. These are planning-side decisions. - Drop provider lenses, idempotency check, dispatch code, synthesis template, anti-patterns, and the "Future refactor (open question)" note — those now live in skills/brainstorm/SKILL.md. - Update the Output files note for brainstorm.md to credit flow:brainstorm as the author. - Update the Workflow step that decides whether to brainstorm to point at the new section name and the flow:brainstorm invocation. - Add flow:brainstorm to the Reference list. No behavior change for users: the size matrix still triggers the same runs; the invocation simply fans out to a different skill.
Add a short paragraph after the Candidate approaches template explaining when research should *suggest* /flow:brainstorm as the next step: 3+ viable shapes with comparable risk/effort, or explicit user request for option-generation. Advisory only — no auto-dispatch; the user or flow:orchestrate decides whether to fan out before flow:plan. Add flow:brainstorm to the Reference list.
Reflect the brainstorm extraction in the orchestrate sequence and skip-logic table: - Sequence ASCII: brainstorm becomes step 3 (between research and plan), not a nested sub-step under plan. Note that research may *suggest* brainstorm but does not dispatch. - Skip-logic table: brainstorm gets its own row instead of an indented ↳ row under plan. Same size-based defaults (skip / ask / yes). - Prose: mention that flow:brainstorm is also invocable standalone outside the orchestrate pipeline. - Frontmatter description and Reference list updated to include flow:brainstorm. No behavior change for the default size-M/L paths — brainstorm fires at the same logical point, just rendered as a peer step.
- plugin.json: insert ./skills/brainstorm/ between ./skills/research/ and ./skills/plan/ (pipeline order); bump version 0.8.0 → 0.9.0; update description to include brainstorm in the pipeline. - marketplace.json: mirror metadata.version + plugins[0].version to 0.9.0; update plugin description to match. Both files in one commit per CLAUDE.md sync rule. Verified with jq: plugin.json .skills length == 9 and .version == "0.9.0"; marketplace.json .metadata.version and .plugins[0].version both == "0.9.0".
- Add brainstorm to the pipeline arrow at the top. - Insert one row between flow:research and flow:plan in the Skills table describing standalone and sub-phase invocation.
- directory-structure.md: brainstorm.md and brainstorms/ are now authored by flow:brainstorm (direct invocation or sub-phase from flow:research / flow:plan). Drop the size-based trigger comment — those rules live in the skill, not the layout doc. - directory-structure.md: add a Naming rules bullet for the new standalone brainstorm variant .planning/<yyyy-mm-dd>-brainstorm-<slug>/ alongside the existing pr<N>-review precedent. Slug derivation: 4–6 kebab-cased content words; collisions get -2, -3. - frontmatter.md: update the brainstorm and brainstorm-contribution type headers to attribute authorship to flow:brainstorm.
gitgitWi
left a comment
gitgitWi
left a comment
There was a problem hiding this comment.
코드 리뷰 요약 — PR #4
전체 평가
추출 자체는 깔끔하고 충실 — flow:plan:52-202의 메커니즘이 누락 없이 skills/brainstorm/SKILL.md로 옮겨졌고, manifest sync(0.9.0)·cross-skill 링크·plan의 non-goals 모두 일관됨. 다만 모델 ID 표류(gemini-3.1-pro vs gemini-3.1-pro-preview)가 3개 리뷰어에 의해 지적된 합의 사항이고, standalone 모드의 idempotency 버그가 1개 리뷰어에 의해 식별됨. 두 이슈를 머지 전에 픽스 권장.
합의된 주요 이슈
- [MAJOR] 모델 ID 표류 —
skills/brainstorm/SKILL.md:104(provider roles)와:210(synthesis frontmatter)이gemini-3.1-pro를 사용하지만references/models.md는gemini-3.1-pro-preview만 등록됨. dispatch 스니펫(:144)은-preview를 정확히 씀 → 같은 파일에서 라벨/실행 ID가 불일치. plan/SKILL.md에서 옮겨온 기존 문제이지만 standalone skill에서 더 눈에 띔. flagged by gpt-5.5, kimi-k2.6, deepseek-v4-pro - [MAJOR] standalone 모드 idempotency 우회 버그 —
skills/brainstorm/SKILL.md:70슬러그 충돌 시-2,-3무조건 append →$TASK_DIR이 항상 신규 빈 디렉토리로 해석되어 직후의 idempotency 체크가 작동하지 않음. 동일 slug 재실행 시 keep/regenerate 선택지 없이 매번 새로 dispatch. flagged by gemini-3.1-pro-preview
diff hunk 밖 발견 사항 (인라인 첨부 불가)
- [MINOR]
references/models.md:12— Kimi/DeepSeek 행의 Use-for 텍스트가 review-only로 남아 있음. brainstorm skill이 두 모델에 risk/security 렌즈를 새로 할당했지만 레지스트리는 "Plan review, code review"만 명시,:26의 "reserve OpenCode for review steps" 코멘트도 standalone brainstorm 흐름과 충돌. follow-up PR에서 두 행의 Use-for와 cost note를 갱신 필요. signed: gpt-5.5 - [MINOR]
skills/orchestrate/SKILL.md:100— Failure handling이 새 peer step brainstorm을 다루지 않음. bullet에 brainstorm을 recoverable로 추가하고, reviewer CLI quorum 정책 bullet에 brainstorm도 동일 정책 적용임을 한 줄 추가 필요. signed: gpt-5.5
모델 간 의견이 갈리는 지점
- 머지 판정이 codex만
request changes, 나머지 3은merge after minor edits. codex는 모델 ID 표류를 MAJOR로, kimi/deepseek은 MINOR/NIT로 판단. 표류가 실행 동작은 망가뜨리지 않지만 (CLI 호출은 정확함), 레지스트리 단일 출처 원칙(plan에 명시)을 거스르므로 codex의 엄격 판정이 합리적임 — 단 머지 자체를 막을 사안은 아니므로 합의된 머지 권장은 "조건부". - standalone idempotency는 codex/kimi/deepseek 모두 놓침. gemini만 발견. 이는 신규 codepath(
-2,-3규칙)에서만 발생하므로 plan에서 옮겨오면서 새로 만들어진 회귀이고, gemini가 단독으로 잡은 실제 버그.
인라인 코멘트 개수
- CRITICAL: 0 / MAJOR: 2 / MINOR: 5 / NIT: 1 / QUESTION: 1 — 인라인 총 9개
- diff 밖 추가 발견: MINOR 2개 (위 섹션)
- 전체: 11개
머지 권장
조건부 권장 — 위 두 MAJOR 픽스 후 머지. MINOR/NIT/QUESTION은 follow-up PR로 다뤄도 무방하나, 모델 ID 정합성(references/models.md 갱신)은 본 PR에서 같이 처리하는 게 깔끔.
모델별 리뷰 원본
.planning/2026-05-17-extract-brainstorm-skill/code-reviews/code-codex.md.planning/2026-05-17-extract-brainstorm-skill/code-reviews/code-gemini.md.planning/2026-05-17-extract-brainstorm-skill/code-reviews/code-kimi.md.planning/2026-05-17-extract-brainstorm-skill/code-reviews/code-deepseek.md
(council-flow의 .planning/은 gitignore되어 있어 PR diff에는 포함되지 않습니다. 로컬 워크트리 extract-brainstorm-skill에서 확인 가능.)
| when size is L or the user requested a security lens. Each model gets a | ||
| **focused lens** so outputs are differentiated, not duplicated. | ||
|
|
||
| - **`gemini-3.1-pro` — Architecture & alternatives.** Surface 2–3 distinct |
There was a problem hiding this comment.
[MAJOR] Provider role과 synthesis frontmatter가 references/models.md에 없는 모델 ID를 씀
이 줄의 provider role 라벨은 gemini-3.1-pro, 같은 파일 :210 synthesis frontmatter의 contributors:도 gemini-3.1-pro. 그러나 references/models.md:10은 gemini-3.1-pro-preview만 등록하고, 실제 dispatch 스니펫 :144도 --model gemini-3.1-pro-preview. 같은 파일 안에서 라벨/실행 ID가 어긋남 → "Model IDs come from references/models.md"라는 본인 명시(:114-115)와 모순. plan/SKILL.md에서 옮겨온 기존 문제지만, standalone skill로 분리된 지금이 정리 적기.
수정 방향: provider role과 frontmatter 예시 모두 gemini-3.1-pro-preview로 통일하거나, references/models.md에 gemini-3.1-pro를 alias로 명시. 후자는 추가 작업이 필요하므로 전자 권장.
— signed: gpt-5.5, opencode-go/kimi-k2.6, opencode-go/deepseek-v4-pro
| - Create | ||
| `<repo-root>/.planning/<yyyy-mm-dd>-brainstorm-<slug>/` (today's date, | ||
| local timezone). If the directory already exists for the same date+slug, | ||
| append `-2`, `-3` until unique. This mirrors the existing |
There was a problem hiding this comment.
[MAJOR] Slug 충돌 시 -2, -3 무조건 append → idempotency 체크가 영원히 작동 안 함
standalone 모드에서 동일 brief를 같은 날 재실행하면, <slug> 디렉토리가 이미 있을 때 무조건 <slug>-2 같은 새 디렉토리를 만들고 $TASK_DIR을 그쪽으로 잡음. 직후의 Idempotency precondition 체크(:81-89)는 비어 있는 새 디렉토리에서 brainstorm.md를 찾지 못해 결국 항상 새로 dispatch — 사용자에게 keep/regenerate/abort를 물어볼 기회 없이 매번 중복 실행되고 audit trail이 분산됨.
수정 방향:
- 기존 `<repo-root>/.planning/<yyyy-mm-dd>-brainstorm-<slug>/`가 있으면 그것을 `$TASK_DIR`로 채택 (idempotency 체크가 이어서 처리). `-2`, `-3` 접미는 사용자가 동일 slug의 별도 세션을 명시적으로 원할 때만.— signed: gemini-3.1-pro-preview
| @@ -0,0 +1,272 @@ | |||
| --- | |||
| name: brainstorm | |||
| description: Run a multi-LLM brainstorming round and synthesize a single `brainstorm.md` (plus per-model raw outputs under `brainstorms/`) surfacing architecture options, hidden risks, and security/correctness angles for an upcoming change. Use this whenever the user wants to weigh "options", "alternatives", "다각도로 보자", a "second opinion before planning", or whenever a non-trivial change benefits from diverse perspectives BEFORE the planner commits to a shape. Invoked directly by the user (`/flow:brainstorm`), or as an optional sub-phase from `flow:research` / `flow:plan`. Runs without any prior `.planning/` directory — accepts an inline task brief when needed. | |||
There was a problem hiding this comment.
[MINOR] Frontmatter description이 너무 넓어 over-fire 위험
"whenever a non-trivial change benefits from diverse perspectives BEFORE the planner commits to a shape" 문구는 Claude Code 자동 invoke 휴리스틱에서 size-M 작업 다수에 매칭될 수 있음. 본 skill의 "plain M은 default-no" 의도(:18)와 충돌.
수정 방향: 명시적 트리거에 가까운 표현으로 좁힘 — "explicitly asks for options/alternatives/다각도/second opinion, or a cross-module / security-sensitive / public-surface change" 정도.
— signed: gemini-3.1-pro-preview
| RUNLOG_ARCH="$TASK_DIR/brainstorms/_runlog-architecture-gemini.txt" | ||
|
|
||
| # Build the read-list for the contributor prompt. research.md is optional. | ||
| READ_LIST="$TASK_DIR/meta.md" |
There was a problem hiding this comment.
[MINOR] READ_LIST가 상대 경로 그대로 contributor에게 전달됨
원본 plan/SKILL.md의 dispatch prompt는 <abs>/meta.md, <abs>/research.md라는 placeholder로 "절대 경로를 쓰라"는 신호를 명시했음. 새 코드는 $TASK_DIR/meta.md를 그대로 넘기는데, pipeline 케이스에서 $TASK_DIR은 .planning/<date>-<task>/ 같은 상대 경로 → contributor CLI가 다른 CWD에서 호출되는 환경에서 silent fail.
현재는 gemini --yolo가 orchestrator의 CWD를 그대로 상속해 작동하지만, future contributor가 다른 CWD를 가지면 깨짐. 수정 방향: input precedence 해석기에서 $TASK_DIR을 realpath로 절대화하거나, prompt 안에서 명시적으로 절대 경로화 단계 추가.
— signed: opencode-go/deepseek-v4-pro
| )" > "$RUNLOG_ARCH" 2> "$RUNLOG_ARCH.stderr"; \ | ||
| echo $? > "$RUNLOG_ARCH.exit" ) || true & | ||
|
|
||
| # Run watch_review (from multi-llm.md) in parallel so progress is visible at 1-min resolution. |
There was a problem hiding this comment.
[MINOR] watch_review 호출이 exit sidecar를 빠뜨려 위치 인자가 어긋남
dispatch 래퍼는 $RUNLOG_ARCH.exit를 정확히 작성하지만(:171), watcher는 watch_review "$REVIEW_ARCH" 25 &로 호출됨. references/multi-llm.md:170, 228의 시그니처는 watch_review <review-file> [<exit-file>] [<max-checks>] — 즉 두 번째 위치 인자가 exit-file. 현재 호출은 25가 exit-file 인자로 해석되어 max_checks 기본값 25가 그대로 쓰이고, CLI가 일찍 죽었을 때 즉시 종료하지 못함.
수정 방향: watch_review "$REVIEW_ARCH" "$RUNLOG_ARCH.exit" 25 &
— signed: gpt-5.5
|
|
||
| If it does, **do not silently re-dispatch.** Ask the user: (a) keep the | ||
| existing synthesis and exit, (b) regenerate (the existing `brainstorm.md` and | ||
| `brainstorms/` files are moved to `brainstorm.v<N>.md` / `brainstorms.v<N>/`, |
There was a problem hiding this comment.
[MINOR] brainstorm.v<N>.md 버전 컨벤션에 대응되는 frontmatter type이 없음
idempotency 섹션은 regenerate 시 기존 brainstorm.md를 brainstorm.v<N>.md로 리네임하라고 안내(plan.v.md 미러). 그런데 references/frontmatter.md에는 plan-version, tasks-version 타입은 있지만 brainstorm-version이 없음. 버전된 brainstorm 파일이 만들어지면 type: 필드의 canonical 값이 없는 상태.
발생 빈도는 낮지만 명시적 갭. 수정 방향: (a) frontmatter.md 타입 표에 brainstorm-version 추가, 또는 (b) 버전 안내를 type: brainstorm + status: superseded + superseded_by로 바꿈.
— signed: opencode-go/deepseek-v4-pro
| - Derive a **slug** from the brief: first 4–6 content words, kebab-cased, | ||
| stopwords (`a`, `the`, `for`, `to`, `with`, `and`, `or`) stripped, ASCII | ||
| only. Example brief: "Should we move auth tokens out of localStorage into | ||
| httpOnly cookies?" → `auth-tokens-localstorage-cookies`. |
There was a problem hiding this comment.
[NIT] Slug 도출 예시가 명시된 stopword 리스트와 일치하지 않음
규칙은 stopwords로 a, the, for, to, with, and, or만 나열. 예시 brief "Should we move auth tokens out of localStorage into httpOnly cookies?" → auth-tokens-localstorage-cookies 결과는 out, of, into, httpOnly를 떨궜는데 이 중 stopword 리스트에 있는 건 하나도 없음.
수정 방향: (a) stopword 리스트에 흔한 전치사(of, out, into, on, in) 추가, 또는 (b) 예시를 규칙대로 동작했을 때의 결과로 교체. 둘 중 어느 쪽이든 사용자가 일관된 slug를 만들 수 있게 해야 함.
— signed: opencode-go/kimi-k2.6
| the whole point of `../../references/multi-llm.md`. | ||
| - **Don't let the brainstorm become the plan.** The planner still drafts | ||
| `plan.md`. Brainstorm is option-generation; plan is decision. In standalone | ||
| mode, `brainstorm.md` is the final artifact — but it still presents options, |
There was a problem hiding this comment.
[QUESTION] "brainstorm과 plan-review 동시 실행 금지" 안티패턴이 pre-plan sketch 케이스를 다루지 않음
brainstorm-then-plan-review의 round-trip 케이스는 명확. 그런데 세 번째 시나리오 — 사용자가 sketch 단계에서 standalone brainstorm을 돌리고, 이후 flow:prep + flow:plan + flow:plan-review를 같은 주제로 새로 돌리는 — 가 있음. 이 경우 brainstorm과 plan-review는 서로 다른 artifact(sketch vs drafted plan)에 적용되어 안티패턴이 해당 안 되는데, 본문엔 그 nuance가 없음.
버그는 아니나 reviewer가 헷갈릴 수 있음. "sketch에 대한 brainstorm ≠ drafted plan에 대한 brainstorm; 안티패턴은 후자에만 적용" 정도의 한 줄 추가 검토.
— signed: opencode-go/deepseek-v4-pro
| ├── brainstorms/ # raw per-model brainstorming outputs, written by `flow:brainstorm` | ||
| │ ├── architecture-gemini.md | ||
| │ ├── risk-kimi.md | ||
| │ └── security-deepseek.md # size L only by default |
There was a problem hiding this comment.
[MINOR] 트리 코멘트 # size L only by default가 brainstorm skill의 실제 트리거와 불일치
security-deepseek.md 옆 코멘트는 size L 전용으로 표기. 그런데 skills/brainstorm/SKILL.md:38-39와 plan의 트리거 매트릭스는 "size L, or size M with security-sensitive surface"로 명시. M+security-sensitive 케이스가 누락됨.
수정 방향: # size L, or M with security-sensitive surface로 갱신.
— signed: opencode-go/deepseek-v4-pro
1 participant
개요
flow:plan내부 sub-phase였던 multi-LLM 브레인스토밍을 독립 skillflow:brainstorm으로 분리.flow:research·flow:plan에서 optional sub-phase로 호출하거나, 사용자가/flow:brainstorm으로 직접 호출 가능. dependency 없이 인라인 task brief로도 단독 실행됨.skills/plan/SKILL.md:200-202에 명시되어 있던 "Future refactor (open question)" 노트를 이 PR로 해소.변경 사항
skills/brainstorm/SKILL.md— provider lenses, 디스패치 계약, idempotency 체크, 합성 템플릿, anti-patterns를 그대로 옮겨옴. 입력 우선순위 3단계 (research.md → meta.md → 인라인 brief + ad-hoc.planning/<yyyy-mm-dd>-brainstorm-<slug>/).skills/plan/SKILL.md— ~150줄 브레인스토밍 본문을 ~40줄 "Optional brainstorming sub-phase" 포인터로 축소. 사이즈 기반 트리거 매트릭스 유지. "Future refactor" 노트 제거.skills/research/SKILL.md— Candidate approaches 끝에 advisory 핸드오프 문단 추가 (auto-dispatch 아님).skills/orchestrate/SKILL.md— 시퀀스 ASCII / 스킵 매트릭스에서 brainstorm을 plan 하위가 아닌 peer step으로 승격. 표준 파이프라인 동작은 동일..claude-plugin/plugin.json—./skills/brainstorm/등록 (research/와 plan/ 사이),version 0.8.0 → 0.9.0, description 갱신..claude-plugin/marketplace.json—metadata.version+plugins[0].version미러링, description 동기. CLAUDE.md sync 규칙대로 한 커밋에 같이 변경.README.md— Skills 표에 한 행 추가, 상단 파이프라인 화살표에 brainstorm 추가.references/directory-structure.md—brainstorm.md/brainstorms/를flow:brainstorm저작으로 재귀속. ad-hoc 변형.planning/<yyyy-mm-dd>-brainstorm-<slug>/네이밍 규칙 추가 (기존pr<N>-review변형과 동일 패턴).references/frontmatter.md—brainstorm,brainstorm-contribution타입의 저자 표기를flow:brainstorm으로 갱신.테스트
이 PR은 순수 문서 + 매니페스트 편집입니다. 실행 코드 변경 없음, 신규 테스트 없음. 구조 검증으로 대체:
jq매니페스트 검증:plugin.jsonskills 9개, version0.9.0;marketplace.jsonmetadata.version/plugins[0].version모두0.9.0.flow:brainstorm참조가 8개 위치(skills/research, plan, orchestrate, brainstorm, references 2종, README, plugin.json)에 모두 존재.skills/brainstorm/SKILL.md프론트매터에name+description필드 정상 파싱.관련 링크
.planning/2026-05-17-extract-brainstorm-skill/plan.md.planning/2026-05-17-extract-brainstorm-skill/tasks.md.planning/2026-05-17-extract-brainstorm-skill/code-reviews/code-summary.md(자동 생성 예정)비호환성 / 마이그레이션
없음. 기존
flow:plan이 만들어둔brainstorm.md파일은flow:brainstorm이 만드는 것과 바이트 단위로 동일 (스키마·본문·brainstorms/레이아웃 모두 보존).flow:develop·flow:deploy·flow:code-review는 brainstorm 산출물을 읽지 않으므로 영향 없음.