Design discussion
Skill firefly-events/plugin-hive/skills/hive/skills/design-discussion
Author a design discussion — turn raw research findings into a comprehensive, opinionated developer brain-dump that states what we're about to do, what worries us, and what's unknown. Use when a /plan run needs its design-discussion document before the design gate.From its SKILL.md
npx -y skills add firefly-events/plugin-hive --skill design-discussionAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
8.1 KB, as published. Nobody here has run it
Hive Design Discussion
Sub-invocation routing
$ARGUMENTS may carry a sub-invocation keyword followed by the epic id, or the epic id alone:
| Invocation form | What fires |
|---|---|
design-discussion {epic-id} | produce-doc then review-doc (default, full mode — backwards-compat) |
design-discussion produce-doc {epic-id} | produce-doc only |
design-discussion review-doc {epic-id} | review-doc only |
Parse $ARGUMENTS:
- If the first token is
produce-doc: execute produce-doc only, with the remaining tokens as the epic id. - If the first token is
review-doc: execute review-doc only, with the remaining tokens as the epic id. - Otherwise: the entire
$ARGUMENTSstring is the epic id. Execute produce-doc first, then review-doc in sequence (full-mode backwards-compat).review-docself-exits early ifplanning.collaborative_reviewisfalse.
Lite-mode callers (e.g. /plan --lite) invoke design-discussion produce-doc {epic-id} directly and never reach review-doc. Full-mode callers invoke design-discussion {epic-id} and get both in sequence.
Sub-invocation: produce-doc
Produce a ~200-line design discussion from raw research findings. This is a
developer brain dump — informal, comprehensive, opinionated. The reader walks away
understanding what the agent thinks it's about to do, what worries it, and what it
doesn't know yet. Canonical structure:
hive/references/document-templates/design-discussion.md.
This skill makes its sections mandatory.
Input: raw research findings (including any INCONSISTENCY_RISK_SIGNALS block),
the original user request, and on a revision pass a grill-record from Phase A2 of
/plan (.pHive/epics/{epic-id}/docs/grill-record.md). $ARGUMENTS carries the epic id.
When to use
- A
/planrun has produced research findings and needs the design-discussion document before the design gate. - A revision pass must fold a grill-record's resolved points back into the design discussion.
Mandatory sections (produce in this order — see template for detail)
- What Are We Doing? (~20 lines) — the requirement restated in the agent's own words.
- What I Found (~40 lines) — the research findings that matter, with file/source citations.
- My Proposed Approach (~40 lines) — the opinionated direction, with rationale.
- What Could Go Wrong (~30 lines) — honest failure modes and worries.
- Dependencies and Constraints (~20 lines) — what this rests on and must respect.
- Open Questions (~20 lines) — unresolved items needing a decision (these surface at the design gate).
- Verification Strategy (~20 lines) — how the resulting work will be proven correct.
- Scale Assessment (~30 lines) — small / medium / large, with the reasoning that drives H/V vs straight-to-stories. End the block with a structured scope-class hint on its own line:
SCOPE_CLASS: single-epic | multi-epic | prd(pick one; this feeds the scope-class guard in/plan --lite).
On a revision pass, add the grill-record consumption per the template (fold resolved points in; do not silently drop contested items).
Completeness gate (do not skip)
All 8 sections present and non-empty. Open Questions and Scale Assessment are
load-bearing (they drive the gate and the H/V decision) — never omit them. If research
didn't cover a section, write [data not provided: <what>] rather than dropping it.
Tone & style
Informal but substantive — a real engineer thinking out loud. Opinionated where the evidence supports it; honest about uncertainty. Cite the surface behind non-obvious claims.
Prose discipline: write the reasoning as paragraphs, not bullet fragments. Bullets are for genuine lists only. A brain-dump that's wall-to-wall bullets reads as a checklist, not thinking. (Prose-heavy planning docs are best authored by a Claude model — codex/code models tend to bullet-dump.)
Output
Write to .pHive/epics/{epic-id}/docs/design-discussion.md.
Where a design includes a visual (wireframe, diagram, or annotated screenshot), embed it using a <figure> slot. Place the slot on its own line between paragraphs so it degrades gracefully in terminal and grep is unaffected:
<figure data-src="state/wireframes/{epic-id}/{story-id}/name.png" data-alt="Brief description">
<!-- placeholder: Brief description -->
</figure>
Use data-src for a known Frame0 PNG path; use data-placeholder="description" (no data-src) when the image does not exist yet. Do not nest prose inside <figure>.
After writing the markdown file, invoke the sidecar HTML generator to produce a .html sibling for browser preview:
python -m hive.lib.html_sidecar_gen ".pHive/epics/{epic-id}/docs/design-discussion.md"
The generator is non-blocking — if it fails, log a warning and continue. The .html file is not committed to git by default (generated on-demand).
After writing the markdown file, record token metrics:
lib/doc-token-telemetry recordDocWrite({ docPath: ".pHive/epics/{epic-id}/docs/design-discussion.md", epicId: "{epic-id}", docType: "design-discussion", format: "md" })
The probe is non-blocking — if it fails, log a warning and continue.
What produce-doc is NOT
- Not the research brief. That structures findings; this reasons about what to do with them.
- Not the structured outline. This is breadth + opinion;
structured-outlineis the detailed blueprint. - Not a decision record. It surfaces open questions for the gate; it does not lock them.
Sub-invocation: review-doc
Run the collaborative review gate on the design-discussion document.
Guard: Read hive.config.yaml → planning.collaborative_review. If false, exit immediately — do not run any review step. (When the default dispatch runs both sub-invocations in sequence, this guard makes review-doc a no-op for projects that opt out.)
Input: .pHive/epics/{epic-id}/docs/design-discussion.md (written by produce-doc) and .pHive/epics/{epic-id}/docs/grill-record.md (written by Phase A2 grill). Both must exist; if either is absent, error out with the missing path.
Review protocol
- Distribute.
SendMessagethe design discussion document and the grill-record to all active team agents simultaneously. - Review. Each agent reviews through their specific lens:
- Researcher: "Are findings accurately represented? Is anything missing from the codebase analysis?"
- TPM: "Is this sequenceable? Are dependencies realistic? Are there delivery risks?"
- Architect (if present): "Is this technically sound? Any feasibility concerns or architectural gaps?"
- UI Designer (if present): "Are UI implications identified? Does the proposed UX align with existing design language?"
- Respond. Each agent returns structured feedback via
SendMessage:REVIEW: {agent-name} VERDICT: approve | flag | approve-with-escalation COMMENTS: {specific issues or confirmation} - Revise. The technical writer revises the draft to address each grill-record finding (or annotates explicitly-accepted-and-justified deviations) and incorporates team feedback. Contested items must be annotated, not silently dropped.
- Extract escalations. After collecting all agent review responses, check each response for escalation signals per the escalation-extraction protocol in
skills/plan/SKILL.md § Collaborative Review Gate. Write extracted flags to.pHive/cycle-state/{epic-id}.yamlwith dedup-on-write.
Output
The revised .pHive/epics/{epic-id}/docs/design-discussion.md (updated in place). No new file is produced; the document's revision history is implicit in the file's final state.