Idea

Standard/Complex Ideas (run elaboration)

Elaboration is a loop, not a straight line. Steps 2–5 below are one round. Keep looping back to chorus_pm_start_elaboration (a new round) until every open question is settled, then resolve once in Step 6. You re-enter the loop whenever:

• the answers to a round derive new questions or surface a contradiction/gap, or
• at the resolve gate (Step 5d / Step 6) the human raises a new concern or correction.

Each new round is just another chorus_pm_start_elaboration call — there is no separate "follow-up" flag, and you do not resolve until the loop is genuinely done. Round cap is 10.

1. Determine depth based on idea complexity:

   • "minimal" — 2-4 questions (small features, minor enhancements)
   • "standard" — 5-10 questions (typical new features)
   • "comprehensive" — 10-15 questions (large features, architectural changes)

2. Create elaboration questions:

   Note: Do NOT include an "Other" option in your questions. The UI automatically adds a free-text "Other" option to every question.

   chorus_pm_start_elaboration({
     ideaUuid: "<idea-uuid>",
     depth: "standard",
     questions: [
       {
         id: "q1",
         text: "What user roles should have access to this feature?",
         category: "functional",
         options: [
           { id: "a", label: "All users" },
           { id: "b", label: "Admin only" },
           { id: "c", label: "Role-based (configurable)" }
         ]
       }
     ]
   })

3. Present questions to the human — through Chorus, never as an unrecorded side conversation. The round you just created is the record; how you reach the human depends on the mode:

   Interactive mode — list every question of the round in chat, numbered, with lettered options matching the option ids, and mark your recommended option:

   Elaboration round 1 (also visible in the Chorus elaboration panel):
   
   1. Which new locales should be prioritized for V1?  [scope]
      a) Japanese only — single locale for initial release (Recommended)
      b) Japanese + Korean — two East Asian locales
   2. ...
   
   Reply like "1a, 2c", or write your own answer for any question.

   After the human replies, map their choices back to option IDs and call chorus_answer_elaboration. If they wrote their own answer ("Other"), set selectedOptionId: null and customText to their input. If they say they answered in the Chorus UI, read chorus_get_elaboration instead of re-asking.

   Gateway mode — post one pointer comment, then end the turn:

   chorus_add_comment({
     targetType: "idea",
     targetUuid: "<idea-uuid>",
     content: "@[Owner Name](user:<owner-uuid>) Elaboration round 1 (<n> questions) is ready for you in the Idea's elaboration panel. Key open points: <one line>."
   })

   Do not poll. When the gateway wakes you (elaboration answered), read the answers with chorus_get_elaboration and continue with item 5. The human answering in the UI submits the answers, so skip item 4 in that case.

4. Submit answers (interactive mode, from the chat replies):

   chorus_answer_elaboration({
     ideaUuid: "<idea-uuid>",
     roundUuid: "<round-uuid>",
     answers: [
       { questionId: "q1", selectedOptionId: "c", customText: null },
       { questionId: "q2", selectedOptionId: null, customText: "Custom hybrid approach" }
     ]
   })

   Answer format:

   • Select an option: selectedOptionId: "a", customText: null
   • Select an option + add a note: selectedOptionId: "a", customText: "additional context"
   • Choose "Other" (free text): selectedOptionId: null, customText: "your answer" — customText is required when no option is selected

   roundUuid is optional on chorus_answer_elaboration. Omit it and the service auto-locates the Idea's single active (pending_answers) round. Pass it explicitly only when you need to target a specific round.

5. Review answers and confirm with the owner (@mention flow):

   After answers are submitted, @mention the answerer (typically the agent's owner) with a summary of your understanding. This prevents misinterpretation before you resolve.

   a. Get owner info from the injected ## Checkin / chorus_checkin response (agent.owner) or search:

   chorus_search_mentionables({ query: "owner-name" })

   b. Post a summary comment on the idea (in both modes — it is the audit trail of the confirmation):

   chorus_add_comment({
     targetType: "idea",
     targetUuid: "<idea-uuid>",
     content: "@[Owner Name](user:owner-uuid) I've reviewed the elaboration answers. Here's my understanding:\n\n- Key requirement 1: ...\n- Key requirement 2: ...\n\nDoes this match your intent?"
   })

   c. Wait for confirmation.

   • Interactive mode: also show the summary in chat and ask "Does this match your intent?"; a chat reply counts, as does a reply comment.
   • Gateway mode: END THE TURN after posting the comment. Do not poll; the gateway wakes you when the owner replies.

   d. Based on the response — this is the loop decision point:

   • Confirmed, nothing left to discuss — Treat this as the human confirmation required to resolve; proceed to Step 6 and call chorus_pm_validate_elaboration.
   • Human raises a new concern / correction / question — Do NOT resolve. Loop back: open a new round with chorus_pm_start_elaboration capturing the new questions, collect answers (Steps 2–5 again), and re-confirm. Repeat until the human has no remaining concerns.
   • The answers themselves derived new questions or a contradiction — Same as above: loop back to chorus_pm_start_elaboration for another round before resolving.
   • Unclear — Ask clarifying questions (in chat when interactive, otherwise via another @mention comment and end the turn), then continue the loop.

6. Resolve the elaboration (the single commit gate — only when the loop is done):

   Resolving marks the whole elaboration phase complete — it sets idea.elaborationStatus = "resolved" (Idea → elaborated), which is the gating signal that lets a downstream Proposal be submitted. It is an Idea-level action (takes only ideaUuid, does not target a round). Resolve once, only after the Step 5d loop has fully settled — every derived question answered and the human has no remaining concerns. If anything is still open, go back to chorus_pm_start_elaboration instead of resolving.

   Precondition: resolve requires the Idea to have at least one round and every round to be fully answered (none left in pending_answers). If a round still has open questions, answer it (or it'll be rejected).

   ⚠️ Human confirmation required. Outside YOLO automation you MUST obtain explicit human confirmation before resolving. The "Confirmed" reply in step 5d above counts as that confirmation. Never resolve on your own judgment alone.

   Permission (N1): chorus_pm_validate_elaboration requires idea:admin. The pm_agent preset only grants idea:write, so a PM-preset agent cannot resolve — it must hand off to an admin_agent-preset agent (or an admin-preset API key) to perform the resolve. If your key lacks idea:admin, surface this to the human (in chat, or via an @mention comment) and request the handoff instead of failing silently.

   Assignee OR idea:admin gateway (N2): the resolving actor may be the Idea's assignee, OR a non-assignee holding idea:admin acting as a resolve gateway (a Chorus permission concept, unrelated to hermes gateway). A gateway resolve (or skip via chorus_pm_skip_elaboration) is the MCP analogue of the human UI Verify-Elaborate: it logs an elaboration_verified activity that wakes the Idea's assignee agent to write the proposal. So an orchestrator/admin no longer needs to claim/reassign the Idea to resolve it — holding idea:admin is enough. (Assignee self-resolve/skip is unchanged and wakes no one.)

   chorus_pm_validate_elaboration({
     ideaUuid: "<idea-uuid>"
   })

   Want a follow-up round instead of resolving? Just call chorus_pm_start_elaboration again — there is no separate "open a round" flag. It works while still elaborating (a normal follow-up round) and, after you've already resolved, as an appended round (isAppended: true) that keeps the Idea elaborated and never blocks an in-flight Proposal. Per-question issue tagging no longer exists.

7. Check elaboration status at any time:

   chorus_get_elaboration({ ideaUuid: "<idea-uuid>" })

Elaboration as audit trail: Even if the user discusses requirements with you outside the formal elaboration flow (for example in a Hermes chat), record key decisions as elaboration rounds so they are persisted and visible to the team.

Question categories: functional, non_functional, business_context, technical_context, user_scenario, scope

Idea Lineage (derive vs. task)

Ideas can form a single-parent forest: an idea may have one parent (parentUuid), establishing a weak lineage. "Weak" means the parent only shows a read-only +N derived rollup of its direct children — it never blocks or alters either idea's elaboration/proposal/task flow, and a parent is always a full first-class idea (it can have its own content, proposals, and tasks).

When a new direction surfaces (during elaboration, brainstorm, or review), decide where it belongs:

• Derive a child idea (chorus_pm_create_idea with parentUuid, or chorus_edit_idea with parentUuid to reparent an existing idea) when the new direction needs its own elaboration/proposal lifecycle — it is an independent AI-DLC pass.
• Add a task to the current idea's proposal when the new work is just how to implement the current idea.
• Create a plain top-level idea (no parentUuid) when there is no lineage to the current idea.

This is a soft heuristic, not a rule — use judgment. Cycle prevention is automatic: you cannot set a parent that is the idea itself or one of its descendants. Parent and child must be in the same project (cross-project lineage is not supported yet). Deleting a parent re-parents its children to top-level (it never cascades).

Theme ideas

A theme is an idea that only groups related children under a shared direction — it is not a deliverable itself. Set isContainer: true on chorus_pm_create_idea / chorus_edit_idea (or the detail-panel toggle) to make one; it is freely reversible. The one rule that matters: a theme cannot create a proposal — to deliver its direction, derive a child idea (parentUuid = <theme>) and write the proposal on the child. A theme may still elaborate (its elaboration is shared context for children), and its status/progress rolls up from its children. Everything else is self-documented on the tool params.

Theme decompose (daemon-assisted)

When a theme is created via the conversational "help me break this into child ideas" entry, don't create children immediately — propose then create: (1) edit the theme + optionally one short scope-elaboration round; (2) propose the candidate children as an elaboration round (chorus_pm_start_elaboration), one single-select question per candidate, for the user to accept/decline in the panel (in gateway mode, post the @mention pointer comment and end the turn); (3) on the answer re-wake, create each accepted child with chorus_pm_create_idea (parentUuid = <theme>, left in open).

Tips

• When combining multiple ideas, explain how they relate in the proposal description
• Elaboration improves Proposal quality — don't skip it unless the requirements are trivially clear, and never without the human's explicit permission
• Every structured question goes through a Chorus elaboration round: list it in chat when the human is there, otherwise @mention the owner and end the turn — never poll
• Record decisions made in conversation as elaboration rounds for auditability
• Always @mention the owner to confirm understanding before resolving

Next

• Once elaboration is resolved, load the proposal skill (skill_view("chorus:proposal")) to create a Proposal with document and task drafts
• Human "Verify Elaborate" handoff: when a human clicks Verify Elaborate on the idea-detail panel, Chorus resolves the elaboration and wakes the Idea's assigned agent (on Hermes, through hermes gateway) to write the proposal — so the woken agent picks up this idea→proposal handoff automatically (no human-authored proposal needed).
• Human "Start Development" handoff: once the proposal is approved and unfinished tasks remain, the idea-detail panel shows a Start Development button (enabled while the assignee agent is online). A start_development wake means: claim and execute ALL remaining tasks of the idea's approved proposal in dependency order until none are claimable — not just one task.
• Human "Yolo" handoff: the idea-detail panel also shows a Yolo button at ANY incomplete stage (enabled while the assignee agent is online), confirmed via a dialog before it fires. A yolo_requested wake means: drive the WHOLE idea to done via the yolo skill (skill_view("chorus:yolo"), the full-auto AI-DLC pipeline) — read the idea's current state first and resume from whatever phase it is in (self-elaborate + write the proposal if not yet resolved; execute if a proposal is approved with open tasks; etc.), never assuming a fixed stage. Complete through done + the completion report, but never merge or push a PR without explicit human approval.
• For platform overview and shared tools, see skill_view("chorus:chorus")