| name | double-diamond-qc |
|---|---|
| description | Two Diamond QC formations in sequence for building a detailed, example-rich study or teaching document that must be both accurate AND clearly explained, because other people will rely on it. Diamond 1 establishes truth; Diamond 2 enriches for clarity (examples, callouts, sidebars, worked problems) while preserving Diamond 1's accuracy; a coordinator owns the handoff brief; a final full-document release gate runs both lenses before publish. This is the engine behind "Canyon Notes" (deep, layered notes), sitting above terse Cliff notes and Cliff Jumper notes. Heavier and more specialized than diamond-qc. Use when the user says "Double Diamond", "Double Diamond QC", or "Canyon Notes", or asks to build a thorough study document that is shared, hard to reverse, and must teach clearly without sacrificing correctness. |
Two diamonds in sequence. The first builds the truth; the second makes it land. Named for the shape: a full Diamond QC, then a second full Diamond QC, joined by a coordinator and closed by a release gate that runs both lenses over the whole document.
It exists because a study document has two failure modes, not one. It can be wrong, and it can be correct but incomprehensible. A single diamond guards the first. The second guards clarity, but clarity is generative: examples, analogies, and "simplifying" callouts are new claims, and new claims can be false or can quietly install a misconception even when literally true. So the second diamond is not a polish pass. It carries the same adversarial burden as the first, aimed at the material it adds.
This skill is a layer over diamond-qc. Each diamond here IS a Diamond QC:
author, two decorrelated auditors, one meta-auditor, verify by evidence not
assertion, escalate by risk not repetition, verify-the-fix. Read diamond-qc
for the per-diamond mechanics. This document specifies only what is added on top:
the second diamond's aim, the coordinator, the spine contract, and the gate.
Match effort to risk, and this is the heavy end. A full Double Diamond is two full diamonds plus a coordinator plus a release gate. That is a lot of agents and tokens. Justify it by stakes, not habit.
- Use it for a high-value study or teaching artifact that is going to other people, is studied and internalized (so a confident wrong example is worse than no example), and must be both correct and genuinely clear. Canyon Notes for a midterm shared with a cohort is the central case.
- Do not use it for terse personal notes, a quick fact-check, code, or
anything one diamond covers. Use
diamond-qc(or plain Cliff notes) instead. Reserve the second diamond for when clarity-by-example is itself a deliverable.
Relationship to the note taxonomy: Cliff notes are terse. Cliff Jumper notes interweave a module. Canyon Notes are deep and layered, enriched with examples and sidebars, and they are what this skill produces.
- A second diamond aimed at clarity, carrying truth's burden. It enriches the verified content and verifies every enrichment on two axes.
- A coordinator (the PM role). Owns the brief, the scope, the detailed-but-not-massive budget, the enrichment plan, final assembly, and convening the release gate. It does not route messages between diamonds.
- A typed spine contract. The handoff between diamonds is a structured, inspectable artifact, not a relayed message. A schema cannot be delivered to the wrong agent.
- A mandatory full-document release gate. Both lenses re-examine the whole assembled document before publish. Required at this scale, because per-addition checks miss regression and cross-section contradictions.
- Presentation as part of the deliverable. A color theme picked once and locked, plus a soft geometric motif applied consistently, so the document relaxes the reader instead of reading as a wall of boxes.
Owns judgment about the handoff, not custody of messages.
- Define. Before Diamond 1, fix the brief: purpose, reader (e.g. you, pre-midterm, plus the cohort it is shared with), scope (which module and topics), the worth bar for what may enter (rule 3), and the visual theme (see Presentation), chosen once and locked.
- Plan the enrichment. After Diamond 1, read the verified spine and decide what genuinely needs an example, callout, or sidebar, and what is already clear. This is the restraint gate. Its default answer is "no addition," overridden only where an enrichment raises comprehension.
- Brief Diamond 2. Hand it the spine, the enrichment plan, the budget, and the hard rule that spine facts are locked.
- Assemble and convene. Integrate Diamond 2's output into the document, apply the locked theme consistently (see Presentation), then convene the release gate.
What the coordinator is not: a router. The diamonds do not address each other and pass notes that could be misdelivered. Flow is orchestrated, and the spine contract is the handoff. A coordinator inserted only to relay would duplicate the orchestration, add a hop and a bottleneck, and guard against a misroute that cannot happen. Give it editorial authority, not the mailbag.
A standard FULL diamond from diamond-qc. Author drafts the accurate content
skeleton and self-verifies; Auditor A checks fidelity to source; Auditor B checks
by execution; the meta-auditor audits them. Its output is the spine contract
below, not loose prose.
A full diamond whose author enriches the spine per the coordinator's brief (examples, worked problems, analogies, callouts, sidebars), then verifies on two decorrelated axes:
- Auditor C, correctness of the addition. Every new example, number, or claim the enrichment introduces is run or traced. The same evidence-not-assertion bar as Diamond 1's Auditor B, applied to the new material.
- Auditor D, fidelity and no-regression. Two jobs. Does each enrichment faithfully represent the spine concept, with no distortion or misconception smuggled in by the simplification? And did the enrichment leave every locked spine fact byte-for-byte intact? This is the axis that protects Diamond 1's truth, and it is the reason the second diamond is adversarial rather than cosmetic.
- Meta-auditor 2. Audits C and D: catches their shared blind spot, overturns false positives, rules on any clarity-versus-fidelity tradeoff (fidelity wins), and enforces the budget against bloat.
Diamond 1 emits the spine as a structured artifact, one entry per verified fact:
id: stable handle the enrichment refers to.claim: the canonical, verified wording.source: citation to lecture, reading, or spec.confidence: calibrated, with any caveat.locked: true. Diamond 2 may build around it and reference it byid, but may not alter its wording or meaning.
Diamond 2's additions attach to spine entries by id. The no-regression check is
then mechanical: every locked claim must appear in the final document unaltered.
A typed contract does the handoff more safely than any relay agent could, because
it is deterministic and inspectable.
A Canyon Note is read for long stretches, so it should relax the reader rather than present as a wall of text, text boxes, and code boxes. Presentation is part of the deliverable, not decoration.
- One theme, picked once, locked. At Define, give each document its own look by selecting a single color theme, then commit to it for the whole document. Variety lives across Canyon Notes; within one, consistency.
- A soft geometric motif. Low-opacity geometric shapes in the background, and a consistent shape language for the borders of text boxes, callouts, sidebars, and code blocks, all drawn from the chosen palette. Calm, not busy.
- Subordinate to content, always. The motif sits behind and around the text and never competes with it. Backgrounds stay low-opacity, contrast stays high, code blocks stay plainly legible.
- It must survive the page. The PDF may be printed and read by others. Keep text readable in grayscale, pick a palette that holds up for color-blind readers, and never carry meaning by color alone.
Presentation is the coordinator's to own and the release gate's to check. It may never buy visual calm at the cost of legibility or of any content rule. A shape that earns nothing is padding, and rule 3 cuts it like any other.
All of diamond-qc's rules apply unchanged. Added here:
- The spine is immutable to Diamond 2. Enrich around verified facts; never over them. Any apparent need to change a spine fact goes back to Diamond 1, not resolved by editing.
- Every enrichment is verified on both axes. Correct in itself, and faithful to the spine. A clear example that distorts the concept fails, even if each sentence is literally true.
- Every element earns its seat. Quality, not quantity. A Canyon Note will be bigger than a Cliff Jumper note. That is expected and fine, it is the deeper tier. Precisely because it grows, size is never the goal and never an excuse: each fact, example, callout, sidebar, and background shape must justify its place by raising comprehension, or it is cut. The failure mode is unearned bulk, not bulk. The coordinator and Meta-auditor 2 enforce this, and the release gate checks for padding.
- The release gate is mandatory at this scale. No document built with this skill ships without the full-document pass below. Per-addition checks are not a substitute.
Phase 0, Define. Coordinator fixes the brief: purpose, reader, scope, budget.
Phase 1, Diamond 1 (Truth). Run a FULL diamond per diamond-qc. Output the
spine contract. Do not proceed until the spine is publish-ready on truth alone.
Phase 2, Handoff. Coordinator reads the spine, writes the enrichment plan (restraint gate), and briefs Diamond 2. Spine facts are locked.
Phase 3, Diamond 2 (Clarity). Author enriches per the plan. Spawn Auditor C (correctness) and Auditor D (fidelity + no-regression) in parallel, then Meta-auditor 2. Apply minimal fixes, verify-the-fix.
Phase 4, Release gate (both lenses, whole document). Over the fully assembled document, run:
- Truth + regression, Diamond 1's lens across everything: every claim still accurate in context, and every locked spine fact intact.
- Clarity + fidelity + seams, Diamond 2's lens across everything: examples hold, nothing in one section contradicts a fact in another, the document reads coherently end to end.
- Presentation + legibility, across everything: the theme is applied consistently, the geometric motif stays subordinate to the text, contrast and grayscale and color-blind legibility hold, and nothing is unearned padding.
- Final sign-off, a meta pass that returns the publish-ready verdict, the minimal fix list, calibrated confidence, and residual risk.
Only after the gate passes is the PDF produced and released.
Scale of fan-out: this is large enough that the deterministic orchestration of the Workflow tool fits well (Diamond 1, then handoff, then Diamond 2, then the gate), but it can also be run by spawning each phase's agents directly. Either way, keep the spine contract as the handoff between phases.
End with a two-diamond scorecard:
- Diamond 1: what each layer caught, fixes applied, the spine's confidence.
- Diamond 2: enrichments added, what C and D caught (with the actual runs for C), any clarity-versus-fidelity rulings, enrichments rejected for not earning their space.
- Release gate: regression result (locked facts intact yes or no), any cross-section contradiction found, the presentation/legibility check, and the final publish-ready verdict.
- A calibrated confidence statement and anything left unverified. No silent caps.
The second diamond's highest-value catches will not be raw factual errors in the examples. They will be the faithful-looking simplification that installs a misconception, and the enrichment edit that quietly reworded a verified fact. Aim Auditor D there. A study document that is wrong but well presented is more dangerous than one that is merely unclear, because it is studied with confidence. That is the whole reason both diamonds, not one, stand between the material and the reader.