[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M759RWSCW7SWJH0A9MDVTB6G":3,"skill-same:01M759RWSCW7SWJH0A9MDVTB6G":65},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":36,"commitSha":37,"skillDirectory":38,"forksCount":39,"repositoryHtmlUrl":40,"repositoryHomepageUrl":6,"ownerHtmlUrl":41,"ownerBlogUrl":42,"ownerDescription":43,"updatedAt":44,"install":45,"resources":58},"01M759RWSCW7SWJH0A9MDVTB6G","brainstorming",null,"You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.","harmoniqs\u002Famicode","harmoniqs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F199011497?v=4","01M759PQCJ9Y093EC5HC3344DW","Harmoniqs","01M759PQD5S85W68FZKV3XD1X0",7,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Fskills\u002Fbrainstorming\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: brainstorming\ndescription: \"You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.\"\nagents: []\nsurface: public\nscenarios: [spec-underspecified-must-block, spec-adequate-must-pass]\nvault_contract:\n  folders: [specs, plans]\n  note_types: [spec, spec-review]\n---\n\n# Brainstorming Ideas Into Designs\n\nHelp turn ideas into fully formed designs and specs through natural collaborative dialogue.\n\nStart by understanding the current project context, then run a grilling skill to reach shared understanding before designing. Once you understand what you're building, present the design and get user approval.\n\n\u003CHARD-GATE>\nDo NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.\n\u003C\u002FHARD-GATE>\n\n## Anti-Pattern: \"This Is Too Simple To Need A Design\"\n\nEvery project goes through this process. A todo list, a single-function utility, a config change — all of them. \"Simple\" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.\n\n## Checklist\n\nYou MUST create a task for each of these items and complete them in order:\n\n1. **Explore project context** — check files, docs, recent commits\n2. **Select & run a grilling skill** — investigate, recommend `grill-me` vs `grill-with-docs`, let the user choose, then invoke it to resolve the design tree to shared understanding\n3. **Propose 2-3 approaches** — with trade-offs and your recommendation\n4. **Present design** — in sections scaled to their complexity, get user approval after each section\n5. **Produce the design-of-record** — render the approved design into the canonical template (two-reader decision-surface layout + density tier; see `write-an-issue`)\n6. **Route it — ask the user the terminus** — vault spec\u002Fplan or GitHub issue — options ordered by the *compounding-why* recommendation (research → spec\u002Fplan first · tooling\u002Farchitecture → issue + repo ADR\u002F`CONTEXT.md` · chore → issue first). Offer the issue option only when `write-an-issue` is in the session's skill index. Draft locally; publish nothing yet\n7. **Review loop** — `amico spec review \u003Cpath>` (the `\u002Fdeliberate` loop: free mechanical tier first, then one-lens critics on the artifact alone); fix and re-run until approved (max 3 rounds, then surface to human)\n8. **User-approve, then publish** — user reviews the local draft; on approval, publish (commit the vault spec\u002Fplan or ADR + `CONTEXT.md`; issue terminus only: `write-an-issue` → `gh issue create`) + bidirectional link. Nothing outward-facing before approval\n9. **Decompose if warranted** — when the terminus is an issue, the design is multi-slice, and `break-into-subissues` is in the session's skill index, invoke it on the published parent to create TDD-ready sub-issues\n\n## Process Flow\n\n```dot\ndigraph brainstorming {\n    \"Explore project context\" [shape=box];\n    \"Select & run grilling skill\" [shape=box];\n    \"Propose 2-3 approaches\" [shape=box];\n    \"Present design sections\" [shape=box];\n    \"User approves design?\" [shape=diamond];\n    \"Produce design-of-record\" [shape=box];\n    \"Ask terminus (spec\u002Fplan or issue)\" [shape=box];\n    \"Review loop\" [shape=box];\n    \"Review passed?\" [shape=diamond];\n    \"User approves draft?\" [shape=diamond];\n    \"Publish (commit \u002F issue if available)\" [shape=doublecircle];\n    \"Break into sub-issues (if multi-slice)\" [shape=box];\n\n    \"Explore project context\" -> \"Select & run grilling skill\";\n    \"Select & run grilling skill\" -> \"Propose 2-3 approaches\";\n    \"Propose 2-3 approaches\" -> \"Present design sections\";\n    \"Present design sections\" -> \"User approves design?\";\n    \"User approves design?\" -> \"Present design sections\" [label=\"no, revise\"];\n    \"User approves design?\" -> \"Produce design-of-record\" [label=\"yes\"];\n    \"Produce design-of-record\" -> \"Ask terminus (spec\u002Fplan or issue)\";\n    \"Ask terminus (spec\u002Fplan or issue)\" -> \"Review loop\";\n    \"Review loop\" -> \"Review passed?\";\n    \"Review passed?\" -> \"Review loop\" [label=\"issues,\\nfix & re-dispatch\"];\n    \"Review passed?\" -> \"User approves draft?\" [label=\"approved\"];\n    \"User approves draft?\" -> \"Produce design-of-record\" [label=\"changes\"];\n    \"User approves draft?\" -> \"Publish (commit \u002F issue if available)\" [label=\"approved\"];\n    \"Publish (commit \u002F issue if available)\" -> \"Break into sub-issues (if multi-slice)\" [label=\"if multi-slice + staged\"];\n}\n```\n\n**The terminal state is the published design-of-record** — a vault spec\u002Fplan or a GitHub issue (via `write-an-issue`, when it is in the session's skill index), bidirectionally linked to any durable record it pairs with. Implementation happens when the work is picked up — a human, or, on a checkout that stages them, the `\u002Fimplement-issue` path (`\u002Fdevelop` for an issue-DAG).\n\n## The Process\n\n**Understanding the idea:**\n\n- Check out the current project state first (files, docs, recent commits)\n- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., \"build a platform with chat, file storage, billing, and analytics\"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.\n- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec -> plan -> implementation cycle.\n- For an appropriately-scoped project, **delegate the interrogation to a grilling skill** (next) — do NOT run your own clarifying-questions loop. The grilling skill owns the entire human-interrogation surface: scoping, purpose, success criteria, and decision-tree resolution.\n\n**Select & run a grilling skill:**\n\nAfter exploring context and before synthesising approaches, pick ONE grilling skill, run it **once**, and let it resolve the design tree to shared understanding.\n\n1. **Investigate** — from the codebase exploration, gather signals: does the repo carry a glossary (`CONTEXT.md` \u002F `CONTEXT-MAP.md`) or ADRs (`docs\u002Fadr\u002F`)? does the design introduce or redefine domain terms? are there bounded-context boundaries or hard-to-reverse decisions?\n2. **Recommend** — propose one skill, with reasoning tied to those signals (table below).\n3. **Choose** — present both options (recommendation first); the user picks; invoke the chosen skill.\n\n| Recommend **grill-with-docs** when any hold | Recommend **grill-me** when |\n|---|---|\n| Repo has `CONTEXT.md` \u002F `CONTEXT-MAP.md` \u002F `docs\u002Fadr\u002F` | None of those exist and domain-language is not at stake |\n| The design introduces, redefines, or disambiguates domain terms | Terminology is already settled \u002F not load-bearing |\n| Bounded-context boundaries are in play | Single-context, localised change |\n| Hard-to-reverse, surprising, trade-off decisions worth an ADR | Easily-reversible \u002F exploratory \u002F greenfield sketch |\n\nThe heuristic keys on **domain-language stakes**, not merely file presence (introducing\u002Fredefining terms recommends `grill-with-docs` even where no `CONTEXT.md` exists yet — it creates one lazily). **No decisive signal** (greenfield, stakes unclear pre-grilling) → recommend `grill-me` (the lighter option) but present both. The user may always override.\n\n> **Gate:** Do NOT synthesise the design until a grilling skill has been run to shared understanding.\n\n**Exploring approaches:**\n\n- Propose 2-3 different approaches with trade-offs\n- Present options conversationally with your recommendation and reasoning\n- Lead with your recommended option and explain why\n\n**Presenting the design:**\n\n- Once you believe you understand what you're building, present the design\n- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced\n- Ask after each section whether it looks right so far\n- Cover: architecture, components, data flow, error handling, testing\n- Be ready to go back and clarify if something doesn't make sense\n\n**Design for isolation and clarity:**\n\n- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently\n- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?\n- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.\n- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.\n\n**Working in existing codebases:**\n\n- Explore the current structure before proposing changes. Follow existing patterns.\n- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.\n- Don't propose unrelated refactoring. Stay focused on what serves the current goal.\n\n## After the Design\n\nOnce the design is approved, **produce → route → draft → publish** a single *design-of-record*. brainstorming owns this flow; the template lives in `write-an-issue`, and the layout itself — the two-reader **decision surface** (`> [!IMPORTANT]`: Problem · Approach · Scope · Assumptions, over execution detail: Acceptance Criteria · Key Decisions · Constraints & Invariants) — is rendered right below (**1. Produce**).\n\n**1. Produce.** Render the approved design into the canonical template — the two-reader **decision-surface layout** (`> [!IMPORTANT]` surface: Problem · Approach · Approaches Considered · Scope · Assumptions, over execution detail: Acceptance Criteria · Key Decisions(+Data Contracts) · Constraints & Invariants · Prior Art · Source · Notes), at **standard** or **PRD** density. Rules: no file paths\u002Fcode, decision-complete, testable criteria, include-if-present.\n\n**2. Route — ask the user the terminus.** The design-of-record's home is the **user's choice**, never the skill's verdict. Ask ONE multiple-choice question — **vault spec\u002Fplan** or **GitHub issue** — and let the *compounding-why* test set only your **recommendation** (the option order and the \"(recommended)\" marker):\n\n*\"Will a future reader (the dream cycle, a researcher, a skill-dev) be worse off if this reasoning vanishes when the issue closes?\"*\n\n| The design's *why* is… | Recommend |\n|---|---|\n| Research \u002F physics (links insights, experiments, papers) | **vault spec\u002Fplan** first (the active vault's `specs\u002Fspec-YYYYMMDD-HHMMSS-\u003Ctopic>.md`; with several mounts, the most restricted one that covers the subject) |\n| amico tooling \u002F architecture (a skill, agent, the workflow) | **GitHub issue** first — the issue is the task — paired with a **repo ADR** (`docs\u002Fadr\u002F`) + `CONTEXT.md` as its durable record |\n| No compounding why (a chore, localized fix) | **GitHub issue** first — the issue is the whole record; a vault spec is usually wasted on it |\n\n**Offer the GitHub-issue option only when `write-an-issue` is in the session's skill index.** Its frontmatter ships `surface: public`, so most installs stage it — but the skill index, not the surface tag, is the staging truth: where the index does not carry it, the terminus is the vault spec\u002Fplan — say so, skip the ask, and never invoke a skill that isn't staged.\n\nThe user's choice is sovereign: a vault spec\u002Fplan is a legitimate terminus even when the issue route exists, and an issue for compounding research is their call. When the issue terminus pairs with a durable record (ADR or spec), **link** to it rather than duplicating it.\n\n**3. Draft locally.** Vault spec\u002Fplan → `vault\u002Fspecs\u002F` (local); ADR + `CONTEXT.md` → repo `docs\u002F`; issue terminus only — the issue body → the **personal vault's `scratchpad\u002F`** (the `rw`\u002F`kind=personal` mount, e.g. `~\u002F.amico\u002Fvaults\u002Farmonia-\u003Cname>\u002Fscratchpad\u002F`; resolve via `amico-vault` rules, don't hardcode the name — see `write-an-issue` step 3). Create nothing outward-facing yet.\n\n**Vault-spec route only** — specs MUST include Amico vault frontmatter:\n  ```yaml\n  ---\n  type: spec\n  date: YYYY-MM-DD\n  session_id: \u003Ccurrent session id>\n  status: draft\n  priority: \u003Cp1|p2|p3>\n  platform: \u003Crelevant platform, e.g. atoms, bosonic, transmon>\n  tags: [spec, \u003Ctopic tags>]\n  visibility: team   # shared research spec → team (federates via dream-promote; promote now via the promote skill). Solo\u002Fscratch → local.\n  linked_plan: null\n  ---\n  ```\n- Use elements-of-style:writing-clearly-and-concisely skill if available\n- **LaTeX-forward math.** All quantitative content must use LaTeX math: inline `$...$`, display `$$...$$`. Never use Unicode math substitutes (γ, σ, ⊗, ∞, ≪, ≳, Δt) in spec bodies — write `$\\gamma$`, `$\\sigma_z \\otimes \\sigma_z$`, `$F_\\infty$`, `$T \\ll T_2^*$`, `$\\Delta t$`. Rationale: specs feed downstream docs and LaTeX reports, and Unicode substitutes silently break equation lookup, copy-paste into `.tex`, and consistency with the specs already in your vault.\n\n**4. Review loop — `amico spec review`, not a reviewer of our own.**\n\n```bash\ncommand -v amico >\u002Fdev\u002Fnull && amico spec review \u003Cpath> --json || echo \"no tooling — review by hand\"\n```\n\n`\u002Fdeliberate` owns this loop; brainstorming calls it rather than carrying a second implementation\nof it. That is not just deduplication:\n\n- **Tier 1 is free and blocks first.** Six mechanical lenses (schema, falsifiable acceptance,\n  budget legality, baseline presence, precedent, provenance) run with no model call, so a spec with\n  prose acceptance never costs a critic. Our own reviewer had no such tier and spent a frontier\n  call to discover a missing threshold.\n- **Critics get one lens each and see the spec file only** — never session history. Same isolation\n  our prompt asked for, now structural rather than requested.\n- **Only `contradiction` may block.** Everything else is an advisory that becomes a tracked\n  obligation on the compiled plan, so it gates *finishing* rather than *starting*. Our loop had no\n  way to carry a finding forward, so a real-but-not-fatal observation was either escalated wrongly\n  or lost.\n- **It records a `spec_review` row**, so \"this was reviewed\" becomes checkable later instead of a\n  claim in a transcript.\n\nExit 65 → revise, `round` up, re-run. Exit 66 (three rounds) → surface to the human.\n`approved-mechanical` or `degraded` → **say so**; neither is `approved`, and reporting either as\n\"reviewed\" is exactly the elision the vocabulary exists to prevent.\n\n**With no `amico` on PATH:** do the review by hand against `\u002Fdeliberate`'s checklists, and say it\nwas manual. A manual review is a weaker claim and must read as one.\n\n**5. User-approve, then publish.** Ask the user to review the local draft:\n\n> \"Drafted to `\u003Cpath>` (terminus: \u003Cvault spec\u002Fplan | ADR + CONTEXT | GitHub issue>). Review it and tell me if you want changes before I publish.\"\n\nOn approval: commit (and push) the vault spec\u002Fplan \u002F ADR \u002F `CONTEXT.md`. **Issue terminus only** — invoke `write-an-issue` → `gh issue create` (it is in the session's skill index, or this route was never offered). Add the **bidirectional link** (issue `## Source` ↔ durable record) whenever both exist. **Nothing outward-facing is created before approval.** If the user requests changes, revise and re-run the review loop.\n\n**6. Decompose (if warranted).** If the terminus is a published issue, the design needs multiple vertical slices, **and `break-into-subissues` is in the session's skill index**, invoke it on the parent issue to produce **TDD-ready sub-issues**. A single small issue needs no decomposition; a vault-terminus design tracks its slices in the spec\u002Fplan body.\n\n**The terminus ends here — at the published design-of-record (plus its sub-issues, if decomposed).** Implementation happens when the work is picked up — a human, or, where the checkout stages them, the `\u002Fimplement-issue` path (`\u002Fdevelop` for an issue-DAG).\n\n## Key Principles\n\n- **One question at a time** - For any *incidental* asking brainstorming does itself (e.g. the scope\u002Fdecomposition gate); the relentless design-refinement interview is delegated to the grilling skill. Don't overwhelm with multiple questions.\n- **Multiple choice preferred** - Easier to answer than open-ended, when brainstorming does ask directly\n- **YAGNI ruthlessly** - Remove unnecessary features from all designs\n- **Explore alternatives** - Always propose 2-3 approaches before settling\n- **Incremental validation** - Present design, get approval before moving on\n- **Be flexible** - Go back and clarify when something doesn't make sense\n","# Brainstorming Ideas Into Designs\n\nHelp turn ideas into fully formed designs and specs through natural collaborative dialogue.\n\nStart by understanding the current project context, then run a grilling skill to reach shared understanding before designing. Once you understand what you're building, present the design and get user approval.\n\n\u003CHARD-GATE>\nDo NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.\n\u003C\u002FHARD-GATE>\n\n## Anti-Pattern: \"This Is Too Simple To Need A Design\"\n\nEvery project goes through this process. A todo list, a single-function utility, a config change — all of them. \"Simple\" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.\n\n## Checklist\n\nYou MUST create a task for each of these items and complete them in order:\n\n1. **Explore project context** — check files, docs, recent commits\n2. **Select & run a grilling skill** — investigate, recommend `grill-me` vs `grill-with-docs`, let the user choose, then invoke it to resolve the design tree to shared understanding\n3. **Propose 2-3 approaches** — with trade-offs and your recommendation\n4. **Present design** — in sections scaled to their complexity, get user approval after each section\n5. **Produce the design-of-record** — render the approved design into the canonical template (two-reader decision-surface layout + density tier; see `write-an-issue`)\n6. **Route it — ask the user the terminus** — vault spec\u002Fplan or GitHub issue — options ordered by the *compounding-why* recommendation (research → spec\u002Fplan first · tooling\u002Farchitecture → issue + repo ADR\u002F`CONTEXT.md` · chore → issue first). Offer the issue option only when `write-an-issue` is in the session's skill index. Draft locally; publish nothing yet\n7. **Review loop** — `amico spec review \u003Cpath>` (the `\u002Fdeliberate` loop: free mechanical tier first, then one-lens critics on the artifact alone); fix and re-run until approved (max 3 rounds, then surface to human)\n8. **User-approve, then publish** — user reviews the local draft; on approval, publish (commit the vault spec\u002Fplan or ADR + `CONTEXT.md`; issue terminus only: `write-an-issue` → `gh issue create`) + bidirectional link. Nothing outward-facing before approval\n9. **Decompose if warranted** — when the terminus is an issue, the design is multi-slice, and `break-into-subissues` is in the session's skill index, invoke it on the published parent to create TDD-ready sub-issues\n\n## Process Flow\n\n```dot\ndigraph brainstorming {\n    \"Explore project context\" [shape=box];\n    \"Select & run grilling skill\" [shape=box];\n    \"Propose 2-3 approaches\" [shape=box];\n    \"Present design sections\" [shape=box];\n    \"User approves design?\" [shape=diamond];\n    \"Produce design-of-record\" [shape=box];\n    \"Ask terminus (spec\u002Fplan or issue)\" [shape=box];\n    \"Review loop\" [shape=box];\n    \"Review passed?\" [shape=diamond];\n    \"User approves draft?\" [shape=diamond];\n    \"Publish (commit \u002F issue if available)\" [shape=doublecircle];\n    \"Break into sub-issues (if multi-slice)\" [shape=box];\n\n    \"Explore project context\" -> \"Select & run grilling skill\";\n    \"Select & run grilling skill\" -> \"Propose 2-3 approaches\";\n    \"Propose 2-3 approaches\" -> \"Present design sections\";\n    \"Present design sections\" -> \"User approves design?\";\n    \"User approves design?\" -> \"Present design sections\" [label=\"no, revise\"];\n    \"User approves design?\" -> \"Produce design-of-record\" [label=\"yes\"];\n    \"Produce design-of-record\" -> \"Ask terminus (spec\u002Fplan or issue)\";\n    \"Ask terminus (spec\u002Fplan or issue)\" -> \"Review loop\";\n    \"Review loop\" -> \"Review passed?\";\n    \"Review passed?\" -> \"Review loop\" [label=\"issues,\\nfix & re-dispatch\"];\n    \"Review passed?\" -> \"User approves draft?\" [label=\"approved\"];\n    \"User approves draft?\" -> \"Produce design-of-record\" [label=\"changes\"];\n    \"User approves draft?\" -> \"Publish (commit \u002F issue if available)\" [label=\"approved\"];\n    \"Publish (commit \u002F issue if available)\" -> \"Break into sub-issues (if multi-slice)\" [label=\"if multi-slice + staged\"];\n}\n```\n\n**The terminal state is the published design-of-record** — a vault spec\u002Fplan or a GitHub issue (via `write-an-issue`, when it is in the session's skill index), bidirectionally linked to any durable record it pairs with. Implementation happens when the work is picked up — a human, or, on a checkout that stages them, the `\u002Fimplement-issue` path (`\u002Fdevelop` for an issue-DAG).\n\n## The Process\n\n**Understanding the idea:**\n\n- Check out the current project state first (files, docs, recent commits)\n- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., \"build a platform with chat, file storage, billing, and analytics\"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.\n- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec -> plan -> implementation cycle.\n- For an appropriately-scoped project, **delegate the interrogation to a grilling skill** (next) — do NOT run your own clarifying-questions loop. The grilling skill owns the entire human-interrogation surface: scoping, purpose, success criteria, and decision-tree resolution.\n\n**Select & run a grilling skill:**\n\nAfter exploring context and before synthesising approaches, pick ONE grilling skill, run it **once**, and let it resolve the design tree to shared understanding.\n\n1. **Investigate** — from the codebase exploration, gather signals: does the repo carry a glossary (`CONTEXT.md` \u002F `CONTEXT-MAP.md`) or ADRs (`docs\u002Fadr\u002F`)? does the design introduce or redefine domain terms? are there bounded-context boundaries or hard-to-reverse decisions?\n2. **Recommend** — propose one skill, with reasoning tied to those signals (table below).\n3. **Choose** — present both options (recommendation first); the user picks; invoke the chosen skill.\n\n| Recommend **grill-with-docs** when any hold | Recommend **grill-me** when |\n|---|---|\n| Repo has `CONTEXT.md` \u002F `CONTEXT-MAP.md` \u002F `docs\u002Fadr\u002F` | None of those exist and domain-language is not at stake |\n| The design introduces, redefines, or disambiguates domain terms | Terminology is already settled \u002F not load-bearing |\n| Bounded-context boundaries are in play | Single-context, localised change |\n| Hard-to-reverse, surprising, trade-off decisions worth an ADR | Easily-reversible \u002F exploratory \u002F greenfield sketch |\n\nThe heuristic keys on **domain-language stakes**, not merely file presence (introducing\u002Fredefining terms recommends `grill-with-docs` even where no `CONTEXT.md` exists yet — it creates one lazily). **No decisive signal** (greenfield, stakes unclear pre-grilling) → recommend `grill-me` (the lighter option) but present both. The user may always override.\n\n> **Gate:** Do NOT synthesise the design until a grilling skill has been run to shared understanding.\n\n**Exploring approaches:**\n\n- Propose 2-3 different approaches with trade-offs\n- Present options conversationally with your recommendation and reasoning\n- Lead with your recommended option and explain why\n\n**Presenting the design:**\n\n- Once you believe you understand what you're building, present the design\n- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced\n- Ask after each section whether it looks right so far\n- Cover: architecture, components, data flow, error handling, testing\n- Be ready to go back and clarify if something doesn't make sense\n\n**Design for isolation and clarity:**\n\n- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently\n- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?\n- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.\n- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.\n\n**Working in existing codebases:**\n\n- Explore the current structure before proposing changes. Follow existing patterns.\n- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.\n- Don't propose unrelated refactoring. Stay focused on what serves the current goal.\n\n## After the Design\n\nOnce the design is approved, **produce → route → draft → publish** a single *design-of-record*. brainstorming owns this flow; the template lives in `write-an-issue`, and the layout itself — the two-reader **decision surface** (`> [!IMPORTANT]`: Problem · Approach · Scope · Assumptions, over execution detail: Acceptance Criteria · Key Decisions · Constraints & Invariants) — is rendered right below (**1. Produce**).\n\n**1. Produce.** Render the approved design into the canonical template — the two-reader **decision-surface layout** (`> [!IMPORTANT]` surface: Problem · Approach · Approaches Considered · Scope · Assumptions, over execution detail: Acceptance Criteria · Key Decisions(+Data Contracts) · Constraints & Invariants · Prior Art · Source · Notes), at **standard** or **PRD** density. Rules: no file paths\u002Fcode, decision-complete, testable criteria, include-if-present.\n\n**2. Route — ask the user the terminus.** The design-of-record's home is the **user's choice**, never the skill's verdict. Ask ONE multiple-choice question — **vault spec\u002Fplan** or **GitHub issue** — and let the *compounding-why* test set only your **recommendation** (the option order and the \"(recommended)\" marker):\n\n*\"Will a future reader (the dream cycle, a researcher, a skill-dev) be worse off if this reasoning vanishes when the issue closes?\"*\n\n| The design's *why* is… | Recommend |\n|---|---|\n| Research \u002F physics (links insights, experiments, papers) | **vault spec\u002Fplan** first (the active vault's `specs\u002Fspec-YYYYMMDD-HHMMSS-\u003Ctopic>.md`; with several mounts, the most restricted one that covers the subject) |\n| amico tooling \u002F architecture (a skill, agent, the workflow) | **GitHub issue** first — the issue is the task — paired with a **repo ADR** (`docs\u002Fadr\u002F`) + `CONTEXT.md` as its durable record |\n| No compounding why (a chore, localized fix) | **GitHub issue** first — the issue is the whole record; a vault spec is usually wasted on it |\n\n**Offer the GitHub-issue option only when `write-an-issue` is in the session's skill index.** Its frontmatter ships `surface: public`, so most installs stage it — but the skill index, not the surface tag, is the staging truth: where the index does not carry it, the terminus is the vault spec\u002Fplan — say so, skip the ask, and never invoke a skill that isn't staged.\n\nThe user's choice is sovereign: a vault spec\u002Fplan is a legitimate terminus even when the issue route exists, and an issue for compounding research is their call. When the issue terminus pairs with a durable record (ADR or spec), **link** to it rather than duplicating it.\n\n**3. Draft locally.** Vault spec\u002Fplan → `vault\u002Fspecs\u002F` (local); ADR + `CONTEXT.md` → repo `docs\u002F`; issue terminus only — the issue body → the **personal vault's `scratchpad\u002F`** (the `rw`\u002F`kind=personal` mount, e.g. `~\u002F.amico\u002Fvaults\u002Farmonia-\u003Cname>\u002Fscratchpad\u002F`; resolve via `amico-vault` rules, don't hardcode the name — see `write-an-issue` step 3). Create nothing outward-facing yet.\n\n**Vault-spec route only** — specs MUST include Amico vault frontmatter:\n  ```yaml\n  ---\n  type: spec\n  date: YYYY-MM-DD\n  session_id: \u003Ccurrent session id>\n  status: draft\n  priority: \u003Cp1|p2|p3>\n  platform: \u003Crelevant platform, e.g. atoms, bosonic, transmon>\n  tags: [spec, \u003Ctopic tags>]\n  visibility: team   # shared research spec → team (federates via dream-promote; promote now via the promote skill). Solo\u002Fscratch → local.\n  linked_plan: null\n  ---\n  ```\n- Use elements-of-style:writing-clearly-and-concisely skill if available\n- **LaTeX-forward math.** All quantitative content must use LaTeX math: inline `$...$`, display `$$...$$`. Never use Unicode math substitutes (γ, σ, ⊗, ∞, ≪, ≳, Δt) in spec bodies — write `$\\gamma$`, `$\\sigma_z \\otimes \\sigma_z$`, `$F_\\infty$`, `$T \\ll T_2^*$`, `$\\Delta t$`. Rationale: specs feed downstream docs and LaTeX reports, and Unicode substitutes silently break equation lookup, copy-paste into `.tex`, and consistency with the specs already in your vault.\n\n**4. Review loop — `amico spec review`, not a reviewer of our own.**\n\n```bash\ncommand -v amico >\u002Fdev\u002Fnull && amico spec review \u003Cpath> --json || echo \"no tooling — review by hand\"\n```\n\n`\u002Fdeliberate` owns this loop; brainstorming calls it rather than carrying a second implementation\nof it. That is not just deduplication:\n\n- **Tier 1 is free and blocks first.** Six mechanical lenses (schema, falsifiable acceptance,\n  budget legality, baseline presence, precedent, provenance) run with no model call, so a spec with\n  prose acceptance never costs a critic. Our own reviewer had no such tier and spent a frontier\n  call to discover a missing threshold.\n- **Critics get one lens each and see the spec file only** — never session history. Same isolation\n  our prompt asked for, now structural rather than requested.\n- **Only `contradiction` may block.** Everything else is an advisory that becomes a tracked\n  obligation on the compiled plan, so it gates *finishing* rather than *starting*. Our loop had no\n  way to carry a finding forward, so a real-but-not-fatal observation was either escalated wrongly\n  or lost.\n- **It records a `spec_review` row**, so \"this was reviewed\" becomes checkable later instead of a\n  claim in a transcript.\n\nExit 65 → revise, `round` up, re-run. Exit 66 (three rounds) → surface to the human.\n`approved-mechanical` or `degraded` → **say so**; neither is `approved`, and reporting either as\n\"reviewed\" is exactly the elision the vocabulary exists to prevent.\n\n**With no `amico` on PATH:** do the review by hand against `\u002Fdeliberate`'s checklists, and say it\nwas manual. A manual review is a weaker claim and must read as one.\n\n**5. User-approve, then publish.** Ask the user to review the local draft:\n\n> \"Drafted to `\u003Cpath>` (terminus: \u003Cvault spec\u002Fplan | ADR + CONTEXT | GitHub issue>). Review it and tell me if you want changes before I publish.\"\n\nOn approval: commit (and push) the vault spec\u002Fplan \u002F ADR \u002F `CONTEXT.md`. **Issue terminus only** — invoke `write-an-issue` → `gh issue create` (it is in the session's skill index, or this route was never offered). Add the **bidirectional link** (issue `## Source` ↔ durable record) whenever both exist. **Nothing outward-facing is created before approval.** If the user requests changes, revise and re-run the review loop.\n\n**6. Decompose (if warranted).** If the terminus is a published issue, the design needs multiple vertical slices, **and `break-into-subissues` is in the session's skill index**, invoke it on the parent issue to produce **TDD-ready sub-issues**. A single small issue needs no decomposition; a vault-terminus design tracks its slices in the spec\u002Fplan body.\n\n**The terminus ends here — at the published design-of-record (plus its sub-issues, if decomposed).** Implementation happens when the work is picked up — a human, or, where the checkout stages them, the `\u002Fimplement-issue` path (`\u002Fdevelop` for an issue-DAG).\n\n## Key Principles\n\n- **One question at a time** - For any *incidental* asking brainstorming does itself (e.g. the scope\u002Fdecomposition gate); the relentless design-refinement interview is delegated to the grilling skill. Don't overwhelm with multiple questions.\n- **Multiple choice preferred** - Easier to answer than open-ended, when brainstorming does ask directly\n- **YAGNI ruthlessly** - Remove unnecessary features from all designs\n- **Explore alternatives** - Always propose 2-3 approaches before settling\n- **Incremental validation** - Present design, get approval before moving on\n- **Be flexible** - Go back and clarify when something doesn't make sense\n",{"name":5,"agents":24,"surface":25,"scenarios":26,"description":7,"vault_contract":29},[],"public",[27,28],"spec-underspecified-must-block","spec-adequate-must-pass",{"folders":30,"note_types":33},[31,32],"specs","plans",[34,35],"spec","spec-review","main","bf84fdd4c1494800695bd5881702b3118dbf98be","packages\u002Fextension\u002Fskills\u002Fbrainstorming",2,"https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode","https:\u002F\u002Fgithub.com\u002Fharmoniqs","harmoniqs.ai","research tools, for researchers, by reseachers","2026-11-12 14:46:24",{"source":8,"skillName":5,"commands":46,"prompt":56,"zipAvailable":57},[47,50,53],{"tool":48,"command":49},"npx","npx skills add harmoniqs\u002Famicode --skill brainstorming",{"tool":51,"command":52},"bunx","bunx skills add harmoniqs\u002Famicode --skill brainstorming",{"tool":54,"command":55},"pnpm","pnpm dlx skills add harmoniqs\u002Famicode --skill brainstorming","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Fskills\u002Fbrainstorming\u002FSKILL.md",true,[59],{"path":60,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":63,"sourceHtmlUrl":64},"spec-reviewer-prompt.md","REFERENCE","参考文档",856,"https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Fskills\u002Fbrainstorming\u002Fspec-reviewer-prompt.md",[66,73,80,86,93,100],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M759XGHEQRJ1GWZTPRFF9Z1W","malformed","Frontmatter that parses as YAML but is missing the required name field.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fmalformed\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M759XDVQ1PYPMT876X8J21TQ","duplicated","Second skill carrying the duplicated frontmatter name.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fdup-two\u002FSKILL.md",[],[],{"skillNo":81,"name":75,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M759XBZYBHF38JDWSRHAC6E1","First skill carrying the duplicated frontmatter name.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fdup-one\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M759XAQBSP29BKTTXR1WF2D7","drifted","A skill whose API claims have drifted from the fixture packages.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fdrifted\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":19},"01M759X8CNBPVK98C6M45D0QMB","clean","A clean skill whose every extracted claim resolves against the fixture packages.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fclean\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":19},"01M759X73H6N2G0VDH8CJ5TF11","broken-paths","A skill with a broken relative link and a broken cited package path.","https:\u002F\u002Fgithub.com\u002Fharmoniqs\u002Famicode\u002Fblob\u002Fmain\u002Fpackages\u002Fextension\u002Ftest\u002Ffixtures\u002Fskill-drift\u002Fskills\u002Fbroken-paths\u002FSKILL.md",[],[]]