jupytermind 0.3.0

package/.github/skills/presentation-planner/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: presentation-planner
+description: >-
+  Plans the content structure and visual design handoff for PowerPoint/PPTX
+  presentations without generating or editing the .pptx file itself. Use for
+  requests like "create a PowerPoint", "make a PPTX", "design a slide deck",
+  "turn this proposal into slides", 「PowerPointを作って」「PPTXを作成して」
+  「提案書をスライドにして」「プレゼン資料の構成を作って」
+  「プレゼンシナリオを作って」. Produces a presentation brief, reusable
+  scenario-based narrative, slide-by-slide outline, design specification,
+  and handoff instructions for the host's dedicated PPTX creation skill. Does
+  NOT implement PPTX generation, python-pptx/PptxGenJS code, binary editing,
+  rendering, thumbnail creation, or visual-overlap inspection; those remain
+  the responsibility of the dedicated PPTX skill. Does NOT handle simple
+  edits to an existing deck, single-slide changes, or direct generation when
+  the storyline and design are already settled; use the dedicated PPTX skill
+  directly for those requests.
+license: MIT
+argument-hint: "[plan|review] <presentation request or source files>"
+---
+
+# presentation-planner
+
+Plans what a presentation must communicate, how the story progresses, and
+which visual system the PPTX renderer must apply. The output is a complete
+handoff package for a dedicated PPTX creation skill, not a `.pptx` file.
+
+## Responsibility boundary
+
+Read `references/responsibility-boundary.md` before acting. This skill owns:
+
+- Audience, objective, decision, and call-to-action definition
+- Scenario selection, audience reasoning journey, and slide ordering
+- One-message-per-slide content architecture
+- Evidence and source mapping
+- Selection and adaptation of a packaged design specification
+- A deterministic handoff contract for the host's PPTX skill
+
+When a presentation request still lacks a defined decision question,
+evidence-backed findings, or option analysis, load kotonoha's sibling
+`consulting-analyst` skill first. Consume its `synthesis-handoff.md` rather
+than inventing business conclusions during storyline design. Preserve its
+evidence IDs, confidence, counterevidence, decision criteria, and conditions
+that would change the recommendation. If the sibling skill is absent, ask for
+the decision question and evidence or label conclusions as unverified.
+
+If the handoff status is `Incomplete`, either return decision-critical gaps
+for further analysis or show the incomplete status, evidence gaps, confidence,
+and conditional wording in the presentation plan. Return to analysis when
+new evidence, a different audience decision, changed criteria, or a
+contradiction would change the conclusion.
+
+This skill must not:
+
+- Create, edit, unzip, or inspect `.pptx` binaries
+- Write PowerPoint generation code using python-pptx, PptxGenJS, COM, or
+  similar libraries
+- Render slides, create thumbnails, or detect visual overlap
+- Reimplement layout or visual QA tooling supplied by the host's PPTX skill
+
+When the host provides a registered `pptx` or PowerPoint creation skill,
+delegate binary generation and visual QA to it. If no such skill is
+available, still produce the five planning artifacts and report
+`PPTX generation not performed`; do not silently implement a renderer.
+
+## Execution modes
+
+- `plan` (default): gather context, produce the five handoff artifacts, and
+  delegate generation when a PPTX skill is available.
+- `review`: review existing brief, scenario, outline, and design spec for
+  audience fit, storyline gaps, evidence gaps, and handoff ambiguity. Do not
+  inspect the binary presentation.
+
+## 0. Route direct PPTX operations away
+
+Before intake, skip this skill and use the dedicated PPTX skill directly
+when any of the following is true:
+
+- The request is a mechanical edit to an existing deck
+- Only one slide, title, image, note, or formatting property must change
+- The user supplied a final scenario, slide outline, and design with no
+  request to restructure them
+- The task is only binary generation, rendering, conversion, or visual QA
+
+Use `presentation-planner` when the audience, storyline, evidence,
+slide sequence, or visual system still needs design.
+
+## 1. Gather context one question at a time
+
+Ask only the single most informative missing question, then wait. Stop once
+the following are known:
+
+1. Target audience and what they already know
+2. The decision, action, or understanding the presentation must produce
+3. Presentation setting: meeting type, speaking time, and target slide count
+4. Source material and evidence that may be cited
+5. Required language, aspect ratio, brand rules, and accessibility needs
+6. Whether an existing `.pptx` or brand template must be reused
+
+If an existing `.pptx` must be reused, ask the host's PPTX skill to inspect
+its theme and layouts. Consume the returned design summary; do not inspect
+the binary in this skill.
+
+## 2. Choose a packaged design specification
+
+Choose the closest design under `assets/design-templates/`:
+
+| Design | Use when | Avoid when |
+|---|---|---|
+| `executive-proposal.yaml` | Approval, investment, roadmap, or executive decision | Dense technical training |
+| `technical-briefing.yaml` | Architecture, engineering explanation, technical proposal | Primarily financial reporting |
+| `data-report.yaml` | KPI review, research findings, operational or analytical reporting | Slides without credible data |
+
+Read `references/design-spec-schema.md` and adapt the selected design into
+the presentation's `design-spec.yaml`. Preserve the schema keys so the PPTX
+skill can consume it predictably.
+
+For project-specific changes or new reusable templates, follow
+`references/customizing-design-templates.md`.
+
+## 3. Build the storyline before slide content
+
+Read `references/scenario-templates.md`, then choose the closest scenario
+under `assets/scenario-templates/`:
+
+| Scenario | Use when |
+|---|---|
+| `executive-decision.md` | Approval, investment, roadmap, policy, or option selection |
+| `technical-briefing.md` | Architecture, engineering behavior, or technical review |
+| `data-report.md` | KPI, research, experiment, survey, or operational analysis |
+
+Copy and adapt it into `presentation-scenario.md`. Use the shortest storyline
+that gets the audience to the intended outcome. The selected template's
+scenario arc is authoritative; keep its stage names unless the adaptation
+records why a stage is removed, merged, or renamed.
+
+When none of the packaged templates fits, use this generic fallback:
+
+1. **Context**: why the audience should care now
+2. **Tension**: the problem, gap, risk, or opportunity
+3. **Evidence**: facts that establish scale and credibility
+4. **Resolution**: the proposed answer or interpretation
+5. **Plan**: actions, owners, cost, timing, and controls
+6. **Decision**: the exact approval, action, or next step
+
+Remove a stage when it adds no decision value. Do not add agenda, section
+divider, or summary slides merely to increase slide count.
+
+## 4. Produce the five handoff artifacts
+
+Write the artifacts under `.presentation/<deck-slug>/` unless the user
+specifies another directory. Derive a stable, filesystem-safe slug from the
+presentation title so multiple decks do not overwrite each other.
+
+### `presentation-brief.md`
+
+Include:
+
+- Working title and one-sentence purpose
+- Audience and prior-knowledge floor
+- Decision or call to action
+- Setting, duration, slide count, language, and aspect ratio
+- Source files and citation expectations
+- Constraints, non-goals, and known unknowns
+- Selected design template and reason
+
+### `presentation-scenario.md`
+
+Copy and adapt one packaged scenario template. If no packaged template fits,
+write the generic fallback arc from §3 into this file using the same fields:
+stage, audience question, assertion, required evidence, transition, and
+suggested slide range. Include:
+
+- Current and intended audience position
+- One assertion and audience question per scenario stage
+- Required evidence, source status, and assumptions
+- The transition that makes the next stage relevant
+- Likely objections, uncertainty, and trade-offs
+- The exact final decision, action, or understanding
+
+The scenario defines the reasoning journey, not individual slide content.
+
+### `slide-outline.md`
+
+Use one row per slide:
+
+| # | Scenario stage(s) | Assertion title | Audience takeaway | Evidence/source | Visual form | Speaker note purpose |
+|---:|---|---|---|---|---|---|
+
+Rules:
+
+- Titles state the slide's conclusion, not its topic
+- Each slide has one primary message
+- Every slide maps to at least one scenario stage; separate multiple stage
+  names with ` / `
+- Evidence is traceable to a source or marked as an assumption
+- Visual form is specific: comparison table, timeline, architecture diagram,
+  annotated chart, process, quote, or full-bleed image
+- A slide must earn its place by advancing the decision or outcome
+
+### `design-spec.yaml`
+
+Copy and adapt one packaged design specification. Set `base_template` to the
+packaged template ID and change `id` to a unique value such as
+`<deck-slug>:<base-template>`. Resolve its placeholders, then record any
+deliberate deviation in a `deviations` list.
+
+### `pptx-handoff.md`
+
+Follow `references/handoff-contract.md`. It must tell the PPTX skill:
+
+- Exact input artifact paths
+- Exact output `.pptx` path
+- Required design template and deviations
+- Slide count and aspect ratio
+- Source and citation rules
+- Required speaker notes and accessibility behavior
+- Binary-generation and visual-QA acceptance checks
+
+## 5. Validate the planning package
+
+Before handoff, verify:
+
+- Reading only assertion titles reproduces the full argument
+- Reading only scenario-stage assertions reproduces the audience journey
+- Every slide maps to at least one stage without introducing an unsupported
+  conclusion
+- The final slide asks for the exact intended decision or action
+- Every factual or quantitative claim has a source or assumption marker
+- No slide has more than one primary message
+- Visual forms vary with the information instead of repeating one layout
+- The design spec contains all required schema keys
+- The handoff assigns all binary and visual checks to the PPTX skill
+
+Use an independent `rubber-duck` reviewer when available. Fix actionable
+findings and repeat for at most five rounds. A round is clean when no
+unaddressed correctness, storyline, evidence, design, or handoff findings
+remain. If the reviewer is unavailable, report `review not performed`. If
+five rounds end with actionable findings, report `review did not converge`
+with the unresolved findings and attempted fixes.
+
+## 6. Delegate PPTX creation
+
+Pass the five artifact paths to the host's dedicated PPTX skill. The PPTX
+skill may choose its own implementation library, but it must preserve the
+approved storyline and design tokens unless it reports a concrete rendering
+constraint.
+
+After generation, require the PPTX skill to report:
+
+- Output file path and slide count
+- Render/thumbnail review result
+- Overlap, clipping, contrast, and font-substitution checks
+- Missing assets or unsupported design instructions
+- Any deviation from `slide-outline.md` or `design-spec.yaml`
+
+Do not claim a presentation is complete from this planning skill alone.

package/.github/skills/presentation-planner/assets/design-templates/data-report.yaml

@@ -0,0 +1,97 @@
+id: data-report
+base_template: null
+intent:
+  - KPI review
+  - research findings
+  - operational report
+  - analytical recommendation
+canvas:
+  aspect_ratio: "16:9"
+  width_in: 13.333
+  height_in: 7.5
+  safe_area_percent: 6
+  grid_columns: 12
+  max_content_blocks: 4
+colors:
+  background: "#FFFFFF"
+  surface: "#F3F3F3"
+  text_primary: "#1B1B1B"
+  text_secondary: "#505050"
+  accent: "#005A9E"
+  accent_soft: "#E5F1FB"
+  border_neutral: "#8A8886"
+  positive: "#107C10"
+  warning: "#8A5A00"
+  critical: "#A4262C"
+  brand_red: "#F25022"
+  brand_green: "#7FBA00"
+  brand_blue: "#00A4EF"
+  brand_yellow: "#FFB900"
+  chart_sequence:
+    - "#005A9E"
+    - "#F25022"
+    - "#767676"
+typography:
+  heading_font: "Aptos Display"
+  body_font: "Aptos"
+  numeric_font: "Aptos"
+  title_size_pt: 28
+  section_title_size_pt: 24
+  body_size_pt: 17
+  metric_size_pt: 34
+  caption_size_pt: 10
+  title_weight: 700
+  body_line_spacing: 1.12
+spacing:
+  outer_margin_percent: 6
+  content_gap_percent: 2
+  card_padding_percent: 2
+components:
+  cards:
+    corner_radius: medium
+    border: none
+    shadow: none
+  callouts:
+    use_accent_bar: false
+    maximum_per_slide: 1
+  tables:
+    header_fill: accent_soft
+    header_text: text_primary
+    zebra_rows: true
+    maximum_rows: 8
+  charts:
+    style: analytical
+    gridlines: minimal
+    direct_labels_required: true
+    series_outline: background
+    source_note_required: true
+    zero_baseline_required_for_bars: true
+  diagrams:
+    connector_style: simple
+    maximum_nodes: 6
+slide_patterns:
+  - title
+  - key-findings
+  - metric-scorecard
+  - trend
+  - comparison
+  - distribution
+  - drivers
+  - implication
+  - recommendation
+  - appendix-method
+accessibility:
+  minimum_body_size_pt: 15
+  minimum_contrast_ratio: 4.5
+  never_use_color_alone: true
+  alt_text_required: true
+constraints:
+  - one primary message per slide
+  - assertion title required
+  - chart axes and units must be visible
+  - uncertainty and sample size must be disclosed
+  - three-dimensional charts are prohibited
+  - Microsoft logo colors are not used for small text on white
+  - brand_yellow uses a direct label and pattern or marker encoding
+  - charts with more than three series add pattern or shape encoding
+deviations: []

package/.github/skills/presentation-planner/assets/design-templates/executive-proposal.yaml

@@ -0,0 +1,92 @@
+id: executive-proposal
+base_template: null
+intent:
+  - executive decision
+  - investment approval
+  - transformation roadmap
+  - technical proposal
+canvas:
+  aspect_ratio: "16:9"
+  width_in: 13.333
+  height_in: 7.5
+  safe_area_percent: 6
+  grid_columns: 12
+  max_content_blocks: 4
+colors:
+  background: "#FFFFFF"
+  surface: "#F3F3F3"
+  text_primary: "#1B1B1B"
+  text_secondary: "#505050"
+  accent: "#005A9E"
+  accent_soft: "#E5F1FB"
+  border_neutral: "#8A8886"
+  positive: "#107C10"
+  warning: "#8A5A00"
+  critical: "#A4262C"
+  brand_red: "#F25022"
+  brand_green: "#7FBA00"
+  brand_blue: "#00A4EF"
+  brand_yellow: "#FFB900"
+  chart_sequence:
+    - "#005A9E"
+    - "#F25022"
+    - "#767676"
+typography:
+  heading_font: "Aptos Display"
+  body_font: "Aptos"
+  title_size_pt: 30
+  section_title_size_pt: 26
+  body_size_pt: 18
+  caption_size_pt: 11
+  title_weight: 700
+  body_line_spacing: 1.15
+spacing:
+  outer_margin_percent: 6
+  content_gap_percent: 2
+  card_padding_percent: 2
+components:
+  cards:
+    corner_radius: medium
+    border: none
+    shadow: subtle
+  callouts:
+    use_accent_bar: true
+    maximum_per_slide: 1
+  tables:
+    header_fill: accent_soft
+    header_text: text_primary
+    zebra_rows: true
+    maximum_rows: 7
+  charts:
+    style: direct-label
+    gridlines: minimal
+    direct_labels_required: true
+    series_outline: background
+    source_note_required: true
+  diagrams:
+    connector_style: orthogonal
+    maximum_nodes: 7
+slide_patterns:
+  - title
+  - executive-summary
+  - problem-evidence
+  - option-comparison
+  - recommendation
+  - roadmap
+  - investment-and-value
+  - risk-and-mitigation
+  - decision-request
+accessibility:
+  minimum_body_size_pt: 16
+  minimum_contrast_ratio: 4.5
+  never_use_color_alone: true
+  alt_text_required: true
+constraints:
+  - one primary message per slide
+  - assertion title required
+  - no more than one chart per slide
+  - no decorative stock imagery without narrative value
+  - Microsoft logo colors are not used for small text on white
+  - brand_yellow uses a direct label and pattern or marker encoding
+  - charts with more than three series add pattern or shape encoding
+deviations: []

package/.github/skills/presentation-planner/assets/design-templates/technical-briefing.yaml

@@ -0,0 +1,96 @@
+id: technical-briefing
+base_template: null
+intent:
+  - architecture explanation
+  - engineering review
+  - technical proposal
+  - implementation briefing
+canvas:
+  aspect_ratio: "16:9"
+  width_in: 13.333
+  height_in: 7.5
+  safe_area_percent: 5
+  grid_columns: 12
+  max_content_blocks: 5
+colors:
+  background: "#FFFFFF"
+  surface: "#F3F3F3"
+  text_primary: "#1B1B1B"
+  text_secondary: "#505050"
+  accent: "#005A9E"
+  accent_soft: "#E5F1FB"
+  border_neutral: "#8A8886"
+  positive: "#107C10"
+  warning: "#8A5A00"
+  critical: "#A4262C"
+  brand_red: "#F25022"
+  brand_green: "#7FBA00"
+  brand_blue: "#00A4EF"
+  brand_yellow: "#FFB900"
+  chart_sequence:
+    - "#005A9E"
+    - "#F25022"
+    - "#767676"
+typography:
+  heading_font: "Aptos Display"
+  body_font: "Aptos"
+  code_font: "Cascadia Mono"
+  title_size_pt: 28
+  section_title_size_pt: 24
+  body_size_pt: 17
+  code_size_pt: 13
+  caption_size_pt: 10
+  title_weight: 700
+  body_line_spacing: 1.12
+spacing:
+  outer_margin_percent: 5
+  content_gap_percent: 1.5
+  card_padding_percent: 1.5
+components:
+  cards:
+    corner_radius: small
+    border: border_neutral
+    shadow: none
+  callouts:
+    use_accent_bar: true
+    maximum_per_slide: 2
+  tables:
+    header_fill: accent_soft
+    header_text: text_primary
+    zebra_rows: false
+    maximum_rows: 8
+  charts:
+    style: technical
+    gridlines: subtle
+    direct_labels_required: true
+    series_outline: background
+    source_note_required: true
+  diagrams:
+    connector_style: orthogonal
+    maximum_nodes: 9
+    boundary_labels_required: true
+slide_patterns:
+  - title
+  - system-context
+  - architecture
+  - sequence-or-flow
+  - component-responsibilities
+  - interface-and-data
+  - security-boundaries
+  - implementation-plan
+  - tradeoffs
+  - decision-request
+accessibility:
+  minimum_body_size_pt: 15
+  minimum_contrast_ratio: 4.5
+  never_use_color_alone: true
+  alt_text_required: true
+constraints:
+  - one primary message per slide
+  - assertion title required
+  - code samples limited to twelve visible lines
+  - diagrams must identify trust or ownership boundaries
+  - Microsoft logo colors are not used for small text on white
+  - brand_yellow uses a direct label and pattern or marker encoding
+  - charts with more than three series add pattern or shape encoding
+deviations: []

package/.github/skills/presentation-planner/assets/scenario-templates/data-report.md

@@ -0,0 +1,47 @@
+# Data report presentation scenario
+
+Use this scenario for KPI reviews, research findings, operational analysis,
+experiments, surveys, or evidence-led recommendations.
+
+- Working title: <presentation title>
+- Audience: <decision-makers or analysts>
+- Question to answer: <one analytical question>
+- Decision or action enabled: <outcome>
+- Analysis period: <date range>
+- Data sources: <systems, files, studies>
+- Target slide count: <count or range>
+
+## Scenario arc
+
+| Stage | Audience question | Assertion to establish | Required evidence | Transition to next stage | Suggested slides |
+|---|---|---|---|---|---:|
+| Question | What decision-relevant question does the analysis answer? | <the question and success measure are unambiguous> | <business context, metric definition> | Explain whether the data can answer it credibly | 1 |
+| Method | How reliable and comparable is the analysis? | <scope, source, sample, and method support the conclusion> | <definitions, coverage, exclusions> | Present the most decision-relevant findings first | 1 |
+| Finding | What changed or differs materially? | <one quantified finding per slide> | <chart, table, confidence, baseline> | Move from observation to explanation | 2–4 |
+| Interpretation | Why did it happen and what uncertainty remains? | <drivers and limitations explain the finding without overstating causality> | <segmentation, comparison, caveats> | Translate the finding into impact | 1–2 |
+| Impact | Why does the result matter? | <finding changes cost, risk, experience, or opportunity> | <scenario, forecast, affected population> | Compare available responses | 1–2 |
+| Recommendation | What action follows from the evidence? | <recommended action is proportional to evidence and uncertainty> | <options, expected effect, cost> | Define measurement and ownership | 1–2 |
+| Next measure | How will we know the action worked? | <owner, metric, target, and review date close the loop> | <measurement plan> | End with the required decision or action | 1 |
+
+## Claim and evidence register
+
+| Claim | Metric definition | Source | Analysis period | Confidence | Caveat |
+|---|---|---|---|---|---|
+| <claim> | <numerator, denominator, unit> | <source> | <period> | High / Medium / Low | <limitation> |
+
+## Analytical integrity checks
+
+- Baseline and comparison periods: <definitions>
+- Population, sample, and exclusions: <definitions>
+- Missing data and outliers: <treatment>
+- Correlation versus causation: <allowed conclusion>
+- Statistical or practical significance: <threshold>
+- Reproducibility: <query, notebook, report, owner>
+
+## Scenario acceptance checks
+
+- The analytical question and metric definitions precede the findings.
+- Each finding slide states one quantified conclusion, unit, period, and source.
+- Limitations and uncertainty appear before recommendations.
+- Recommendations are proportional to the strength of the evidence.
+- The final stage assigns an action, metric, owner, and review date.

package/.github/skills/presentation-planner/assets/scenario-templates/executive-decision.md

@@ -0,0 +1,43 @@
+# Executive decision presentation scenario
+
+Use this scenario when executives or accountable sponsors must approve an
+investment, architecture, roadmap, policy, or delivery decision.
+
+- Working title: <presentation title>
+- Audience: <decision-makers and prior knowledge>
+- Decision required: <one explicit approval or choice>
+- Decision deadline: <date or meeting>
+- Current audience position: <what they believe or question now>
+- Intended final position: <what they should believe and do>
+- Target slide count: <count or range>
+
+## Scenario arc
+
+| Stage | Audience question | Assertion to establish | Required evidence | Transition to next stage | Suggested slides |
+|---|---|---|---|---|---:|
+| Context | Why does this require attention now? | <change, deadline, or opportunity makes action timely> | <external change, KPI, commitment> | If action is timely, show the consequence of inaction | 1–2 |
+| Tension | What happens if we continue as-is? | <current state creates measurable cost, risk, or delay> | <baseline, incident, trend, user impact> | Once the gap is credible, define the decision criteria | 1–2 |
+| Criteria | How should the options be judged? | <shared cost, value, risk, and feasibility criteria> | <constraints, targets, policy> | Compare options using the agreed criteria | 1 |
+| Options | What choices are realistically available? | <credible alternatives include the status quo> | <comparable analysis> | Identify the option that best satisfies the criteria | 1–2 |
+| Recommendation | What should we choose and why? | <recommended option delivers the best justified outcome> | <benefits, trade-offs, TCO, evidence> | Show that execution risk is controlled | 1–2 |
+| Plan | Can this be delivered safely? | <owners, milestones, controls, and rollback make delivery feasible> | <roadmap, staffing, risk controls> | Convert confidence into a precise decision | 1–2 |
+| Decision | What exactly must be approved today? | <specific approval, funding, owner, and next checkpoint> | <decision wording and consequences> | End with the requested action | 1 |
+
+## Evidence gaps and assumptions
+
+| Claim needed by the scenario | Source | Status | Assumption or follow-up |
+|---|---|---|---|
+| <claim> | <file, URL, owner> | Verified / Assumption / Missing | <action> |
+
+## Objections to resolve
+
+| Likely objection | Where it is answered | Evidence or concession |
+|---|---|---|
+| <cost, risk, timing, alternative> | <scenario stage> | <response> |
+
+## Scenario acceptance checks
+
+- Reading only the assertions forms a complete decision argument.
+- The status quo and at least one alternative use the same evaluation axes.
+- Benefits, cost, risks, and delivery controls are evidence-based.
+- The final stage asks for one explicit decision with an owner and deadline.

package/.github/skills/presentation-planner/assets/scenario-templates/technical-briefing.md

@@ -0,0 +1,45 @@
+# Technical briefing presentation scenario
+
+Use this scenario to explain an architecture, engineering change, technical
+proposal, system behavior, or implementation approach to a technical audience.
+
+- Working title: <presentation title>
+- Audience: <engineers, architects, operators, reviewers>
+- Prior-knowledge floor: <what can be assumed>
+- Understanding or decision required: <outcome>
+- Technical depth: Overview / Working knowledge / Review-ready
+- Target slide count: <count or range>
+
+## Scenario arc
+
+| Stage | Audience question | Assertion to establish | Required evidence | Transition to next stage | Suggested slides |
+|---|---|---|---|---|---:|
+| Context | What system and constraint are we discussing? | <boundary, users, and constraints define the problem> | <context diagram, requirements> | Show where the current design fails or must change | 1–2 |
+| Problem | What technical problem must be solved? | <specific quality or delivery gap requires a design response> | <failure mode, measurement, limitation> | State the design drivers used to judge solutions | 1–2 |
+| Drivers | What properties matter most? | <requirements and quality attributes determine the design> | <NFRs, constraints, priorities> | Introduce the architecture that satisfies them | 1 |
+| Architecture | How is the solution structured? | <components and boundaries assign clear responsibilities> | <context, container, deployment diagrams> | Walk through the critical behavior | 2–3 |
+| Flow | What happens in the important scenarios? | <data and control flow meet functional and failure requirements> | <sequence, state, data flow> | Examine trade-offs and failure behavior | 1–3 |
+| Trade-offs | Why this design instead of alternatives? | <accepted costs are justified by the design drivers> | <alternatives, benchmarks, risks> | Show that the design can be operated and evolved | 1–2 |
+| Operations | How will it be secured, observed, scaled, and recovered? | <operational controls make the design production-ready> | <SLO, threat controls, runbook, capacity> | Close with implementation or review actions | 1–2 |
+| Next step | What must the audience do next? | <review decision, implementation step, or open issue is explicit> | <owners, dates, unresolved decisions> | End with the required action | 1 |
+
+## Technical evidence map
+
+| Assertion | Requirement or decision ID | Source artifact | Confidence | Missing validation |
+|---|---|---|---|---|
+| <assertion> | <FR/NFR/ADR/Issue> | <file or URL> | High / Medium / Low | <test or review> |
+
+## Complexity controls
+
+- Terms requiring definition: <terms>
+- Details delegated to appendix: <schemas, exhaustive tables, code>
+- Diagrams required: <context, sequence, data, deployment>
+- Known limitations: <unsupported or deferred behavior>
+
+## Scenario acceptance checks
+
+- The system boundary and design drivers appear before component detail.
+- Architecture diagrams and processing flows carry the primary explanation.
+- Alternatives and accepted trade-offs are explicit.
+- Security, operation, failure, and recovery behavior are not deferred silently.
+- The final stage identifies a review decision or implementation action.