|
| 1 | +--- |
| 2 | +description: "Generate a repo-grounded idea draft via directed-swarm exploration" |
| 3 | +argument-hint: "<idea-text-or-path> [--n <int>] [--output <path>]" |
| 4 | +allowed-tools: |
| 5 | + - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/validate-gen-idea-io.sh:*)" |
| 6 | + - "Read" |
| 7 | + - "Glob" |
| 8 | + - "Grep" |
| 9 | + - "Task" |
| 10 | + - "Write" |
| 11 | +--- |
| 12 | + |
| 13 | +# Generate Idea Draft from Loose Input |
| 14 | + |
| 15 | +Read and execute below with ultrathink. |
| 16 | + |
| 17 | +## Hard Constraint: Draft-Only Output |
| 18 | + |
| 19 | +This command MUST NOT implement features, modify source code, or create commits while producing the draft. Permitted writes are limited to the single output draft file produced in Phase 4; prerequisite directory creation for the default `.humanize/ideas/` path by the validation script is permitted as part of that write. All exploration subagents run read-only. |
| 20 | + |
| 21 | +This command transforms a loose idea into a repo-grounded draft suitable as input to `/humanize:gen-plan`. It applies directed-diversity exploration: a lead picks N orthogonal directions, N parallel `Explore` subagents develop each, the lead synthesizes a draft with one primary direction plus N-1 alternatives. Each direction carries objective evidence from the repo. |
| 22 | + |
| 23 | +## Workflow Overview |
| 24 | + |
| 25 | +> **Sequential Execution Constraint**: All phases MUST execute strictly in order. Each phase fully completes before the next. |
| 26 | +
|
| 27 | +1. Parse Input |
| 28 | +2. IO Validation |
| 29 | +3. Direction Generation |
| 30 | +4. Parallel Exploration |
| 31 | +5. Synthesis and Write |
| 32 | + |
| 33 | +--- |
| 34 | + |
| 35 | +## Phase 0: Parse Input |
| 36 | + |
| 37 | +Extract from `$ARGUMENTS`: |
| 38 | +- First positional: inline idea text or path to a `.md` file (required). |
| 39 | +- `--n <int>`: number of directions. Default 6. |
| 40 | +- `--output <path>`: target draft path. Default resolved by the validation script. |
| 41 | + |
| 42 | +Do not interpret or rewrite the idea text here. Pass `$ARGUMENTS` through to Phase 1 unchanged. |
| 43 | + |
| 44 | +--- |
| 45 | + |
| 46 | +## Phase 1: IO Validation |
| 47 | + |
| 48 | +Run: |
| 49 | +```bash |
| 50 | +"${CLAUDE_PLUGIN_ROOT}/scripts/validate-gen-idea-io.sh" $ARGUMENTS |
| 51 | +``` |
| 52 | + |
| 53 | +Handle exit codes: |
| 54 | +- `0`: Parse stdout to extract `INPUT_MODE`, `OUTPUT_FILE`, `SLUG`, `TEMPLATE_FILE`, `N` (each appears on its own `KEY: value` line). When `INPUT_MODE` is `file`, stdout additionally contains an `IDEA_BODY_FILE: <path>` line; extract that too. Continue to Phase 2. (`SLUG` is informational — the script has already incorporated it into `OUTPUT_FILE`, so later phases do not need to use `SLUG` directly.) |
| 55 | +- `1`: Report "Missing or empty idea input" and stop. |
| 56 | +- `2`: Report "Input looks like a file path but is missing, not readable, or not `.md`" and stop. |
| 57 | +- `3`: Report "Output directory does not exist — please create it or choose a different path" and stop. |
| 58 | +- `4`: Report "Output file already exists — choose a different path" and stop. |
| 59 | +- `5`: Report "No write permission to output directory" and stop. |
| 60 | +- `6`: Report "Invalid arguments" with the stdout usage text and stop. |
| 61 | +- `7`: Report "Template file missing — plugin configuration error" and stop. |
| 62 | + |
| 63 | +Before `VALIDATION_SUCCESS`, stdout may contain one or more lines starting with `WARNING:` (for example, `WARNING: short idea (<N> chars); proceeding` when an inline idea is under 10 characters). Surface these warnings to the user in your final report but continue Phase 2 normally. `WARNING:` lines are informational, not errors. |
| 64 | + |
| 65 | +Obtain the idea body into memory as `IDEA_BODY`, based on `INPUT_MODE`: |
| 66 | +- `inline`: stdout contains a sentinel block at the end of the success output; extract all text between the `=== IDEA_BODY_BEGIN ===` and `=== IDEA_BODY_END ===` lines (exclusive). The script emits a trailing newline after the last body line. |
| 67 | +- `file`: read the full contents of `IDEA_BODY_FILE` using the `Read` tool. |
| 68 | + |
| 69 | +Preserve byte-identical content in memory for later phases. No on-disk tempfile is created in inline mode — the stdout sentinel block is the authoritative source. |
| 70 | + |
| 71 | +--- |
| 72 | + |
| 73 | +## Phase 2: Direction Generation |
| 74 | + |
| 75 | +Generate exactly `N` orthogonal directions for exploring the idea. |
| 76 | + |
| 77 | +### Context to Gather |
| 78 | + |
| 79 | +Before generating directions, read (paths relative to the project root, which is `$(git rev-parse --show-toplevel)`): |
| 80 | +- `README.md` at the project root. |
| 81 | +- `CLAUDE.md` at the project root (if it exists). |
| 82 | +- `.claude/CLAUDE.md` (if it exists). |
| 83 | +- Top-level directory listing via `Glob` with pattern `*` (one level, no recursion). |
| 84 | + |
| 85 | +This context grounds the directions in the actual repo rather than generic brainstorming. |
| 86 | + |
| 87 | +### Generation Rules |
| 88 | + |
| 89 | +Produce exactly `N` direction entries. Each entry has: |
| 90 | +- `name`: a 2-5 word short label. |
| 91 | +- `rationale`: a single sentence explaining why this angle is distinct from the other directions. |
| 92 | + |
| 93 | +Hard constraint: **orthogonality**. Two near-duplicate directions defeat the directed-diversity premise. Before returning: |
| 94 | +- If two directions feel like dupes, replace one with a genuinely different angle. |
| 95 | +- If a direction collapses to "just do X better" with no angle distinction, replace it. |
| 96 | +- Do not emit directions that merely restate the idea in different words. |
| 97 | + |
| 98 | +### Retry and Degradation |
| 99 | + |
| 100 | +- If the first pass returns fewer than `N` entries, regenerate once with an explicit "you MUST produce `N` orthogonal directions" instruction. |
| 101 | +- If the second pass still returns fewer than `N` but at least 2, proceed with the reduced count and emit a warning to the user: `Warning: direction generation returned <count> of <N> requested directions; proceeding with reduced count.` |
| 102 | +- If fewer than 2 directions are produced, stop with error: `direction generation degraded; retry.` |
| 103 | + |
| 104 | +Store the final direction list as `DIRECTIONS` (ordered; index 0..len-1). |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +## Phase 3: Parallel Exploration |
| 109 | + |
| 110 | +Dispatch all directions in a **single Task-tool message** containing one Task invocation per direction. This is the W2S parallel-swarm step. |
| 111 | + |
| 112 | +### Subagent Invocation |
| 113 | + |
| 114 | +For each direction in `DIRECTIONS`, launch one `Explore` subagent. Each invocation prompt MUST include: |
| 115 | + |
| 116 | +1. A verbatim copy of the idea body (`IDEA_BODY`) captured in Phase 1. |
| 117 | +2. The assigned direction (name + rationale). |
| 118 | +3. The following instruction block (reproduce verbatim in the subagent prompt): |
| 119 | + |
| 120 | +> Explore this direction within the current repo. Gather OBJECTIVE EVIDENCE: |
| 121 | +> - Specific repo paths with existing patterns worth extending. |
| 122 | +> - Prior art or precedent in the codebase or adjacent tooling. |
| 123 | +> - Measurable considerations (approximate complexity, LOC surface, performance implications) where discoverable from reading the code. |
| 124 | +> |
| 125 | +> Read-only. Do not write any files. |
| 126 | +> |
| 127 | +> If no concrete evidence exists for this direction, report the literal string `exploratory, no concrete precedent` once in OBJECTIVE_EVIDENCE and stop exploring further. Fabrication of references is forbidden. |
| 128 | +> |
| 129 | +> Return a structured proposal with exactly these fields: |
| 130 | +> - `APPROACH_SUMMARY`: concrete design description (what to build, core mechanism, affected components). |
| 131 | +> - `OBJECTIVE_EVIDENCE`: bullet list of repo paths, prior art, or the `exploratory, no concrete precedent` sentinel. |
| 132 | +> - `KNOWN_RISKS`: short bullet list. |
| 133 | +> - `CONFIDENCE`: one of `high`, `medium`, `low`. |
| 134 | +
|
| 135 | +### Collection and Degradation |
| 136 | + |
| 137 | +Collect all subagent responses. For each response: |
| 138 | +- Parse the four required fields. If a field is missing, mark that proposal as degraded and drop it. |
| 139 | +- If fewer than 2 proposals survive, stop with error: `exploration phase degraded; retry.` |
| 140 | +- Otherwise continue with the surviving proposals. |
| 141 | + |
| 142 | +Associate each surviving proposal with its originating direction (so Phase 4 can label it with the original direction name). When numbering alternatives in Phase 4 after any drops, renumber survivors sequentially as Alt-1..Alt-K (where K is the count of surviving non-primary directions). Do not preserve gaps from dropped proposals. |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +## Phase 4: Synthesis and Write |
| 147 | + |
| 148 | +### Step 4.1: Pick the Primary Direction |
| 149 | + |
| 150 | +Review all surviving proposals. Choose the strongest as the primary based on: |
| 151 | +1. Evidence density — more concrete repo references outranks fewer. |
| 152 | +2. Fit with existing repo patterns — extending patterns outranks introducing unfamiliar paradigms. |
| 153 | +3. Implementation surface area — prefer smaller surface where quality is otherwise comparable. |
| 154 | +4. Declared `CONFIDENCE` — `high` > `medium` > `low` as tiebreaker. |
| 155 | + |
| 156 | +Record the chosen direction as `PRIMARY`; the remaining surviving directions become the Alt-1..Alt-K list (where K is the number of non-primary survivors, K ≤ N-1), numbered sequentially in their original direction order with no gaps for any dropped proposals. |
| 157 | + |
| 158 | +### Step 4.2: Infer Title |
| 159 | + |
| 160 | +Generate a 4-10 word Title Case title that captures the primary direction, not the original input phrasing verbatim. Example: idea `add undo/redo` with primary direction `command-pattern history` yields title `Command-Pattern Undo Stack For The Editor`. |
| 161 | + |
| 162 | +### Step 4.3: Populate the Template |
| 163 | + |
| 164 | +Read the template file located at `TEMPLATE_FILE` (from Phase 1 stdout). |
| 165 | + |
| 166 | +Produce the finalized draft content in memory by replacing placeholders: |
| 167 | +- `<TITLE>` — the inferred title. |
| 168 | +- `<ORIGINAL_IDEA>` — byte-identical value of `IDEA_BODY` captured in Phase 1. Preserve line breaks, trailing newline, and all formatting. Do NOT paraphrase or re-indent. |
| 169 | +- `<PRIMARY_NAME>` — primary direction's short name. |
| 170 | +- `<PRIMARY_RATIONALE>` — primary direction's rationale (from Phase 2). |
| 171 | +- `<PRIMARY_APPROACH_SUMMARY>` — primary proposal's `APPROACH_SUMMARY`. |
| 172 | +- `<PRIMARY_OBJECTIVE_EVIDENCE>` — primary proposal's `OBJECTIVE_EVIDENCE`, rendered as a bullet list. If the subagent returned only the literal sentinel `exploratory, no concrete precedent`, render it as a single bullet: `- exploratory, no concrete precedent`. |
| 173 | +- `<PRIMARY_KNOWN_RISKS>` — primary proposal's `KNOWN_RISKS`, rendered as a bullet list. |
| 174 | +- `<ALTERNATIVES>` — for each non-primary survivor at its Alt index `i` (1-based, sequential per Step 4.1), emit: |
| 175 | + |
| 176 | + ```markdown |
| 177 | + ### Alt-<i>: <name> |
| 178 | + - Gist: <one-paragraph summary derived from APPROACH_SUMMARY> |
| 179 | + - Objective Evidence: |
| 180 | + - <bullet from OBJECTIVE_EVIDENCE> |
| 181 | + - ... |
| 182 | + - Why not primary: <one sentence stating the tradeoff vs PRIMARY> |
| 183 | + ``` |
| 184 | + |
| 185 | + Separate consecutive Alt entries with a single blank line. |
| 186 | + |
| 187 | +- `<SYNTHESIS_NOTES>` — one paragraph describing which elements from the alternatives could fold into the primary if the user chose a different direction. This is the lead's own synthesis note, not a subagent output. |
| 188 | + |
| 189 | +### Step 4.4: Write the Draft File |
| 190 | + |
| 191 | +Write the finalized content to `OUTPUT_FILE` using the `Write` tool. Single write; no progressive edits. |
| 192 | + |
| 193 | +### Step 4.5: Report |
| 194 | + |
| 195 | +Report to the user: |
| 196 | +- Path written (`OUTPUT_FILE`). |
| 197 | +- Primary direction name. |
| 198 | +- Requested `N` and the actual direction count (note if reduced due to degradation). |
| 199 | +- Next-step hint: `To turn this draft into a plan, run: /humanize:gen-plan --input <OUTPUT_FILE> --output <plan-path>`. |
| 200 | + |
| 201 | +--- |
| 202 | + |
| 203 | +## Error Handling |
| 204 | + |
| 205 | +- Phase 1 validation errors stop the command with a clear message. No partial output. |
| 206 | +- Phase 2 degradation follows the retry-once + ≥2 minimum rule stated above. |
| 207 | +- Phase 3 degradation follows the drop-and-continue + ≥2 minimum rule stated above. |
| 208 | +- Never fabricate repo references or prior art. The `exploratory, no concrete precedent` sentinel from subagents is preserved verbatim in the draft. |
| 209 | +- If any phase stops with an error, do not write a partial `OUTPUT_FILE`. |
0 commit comments