kotonoha 0.1.6-dev.0 → 0.3.0

package/README.md

@@ -1,38 +1,65 @@
 # kotonoha
 
-kotonoha provides GitHub Copilot CLI skills for technical documents and
-presentation planning. `tech-writer` helps structure and polish README, design
-docs/ADRs, API reference, PR descriptions/commit messages/issue reports,
-release notes, user manuals/how-to guides, code comments, requirements
-definitions, system designs, test plans, operations runbooks, migration plans,
-security designs, technical proposals, RFI/RFP procurement documents, and
-Qiita/Zenn articles,
-structured so readers never get lost. `presentation-planner` turns source
-material into a reusable presentation scenario, slide outline, design
+kotonoha provides GitHub Copilot CLI skills for consulting analysis, technical
+documents, Japanese prose, and presentation planning. `consulting-analyst`
+structures ambiguous problems into issue trees, hypotheses, evidence, option
+comparisons, and recommendations. `tech-writer` turns that reasoning into
+README, design documents, Blueprints, White Papers, proposals, and other
+technical documents without losing the reader. `japanese-prose` improves
+Japanese wording with GiNZA-based diagnostics. `presentation-planner` turns
+source material into a reusable presentation scenario, slide outline, design
 specification, and handoff for a dedicated PPTX creation skill.
 
+[English](./README.md) | [日本語](./README-ja.md)
+
+## Why the name kotonoha
+
+`kotonoha` comes from the Japanese expression 言の葉 (*kotonoha*), a
+classical and poetic name for words, language, and verse. The name reflects
+this project's purpose: helping a reader's intent grow into clear,
+well-structured words.
+
+Its connection to the *Man'yoshu* needs one qualification. One traditional
+interpretation reads the anthology's title as "countless words or poems,"
+but the title's etymology is not settled. The famous explicit image,
+"Japanese poetry takes the human heart as its seed and grows into myriad
+leaves of words," is from the
+[*Kokin Wakashu* Kana Preface](https://ja.wikisource.org/wiki/%E5%8F%A4%E4%BB%8A%E5%92%8C%E6%AD%8C%E9%9B%86%E4%BB%AE%E5%90%8D%E5%BA%8F),
+not the *Man'yoshu*. The earlier *Man'yoshu* expresses a related belief in
+the power of language through *kotodama*, including poems
+[894](https://manyo-hyakka.pref.nara.jp/db/detailLink?cls=db_manyo&pkey=894)
+and
+[3254](https://manyo-hyakka.pref.nara.jp/db/detailLink?cls=db_manyo&pkey=3254).
+The broader historical meaning of 言の葉 is summarized by
+[Kotobank](https://kotobank.jp/word/%E8%A8%80%E3%81%AE%E8%91%89-503155).
+
 ## What tech-writer solves
 
 Technical documents tend to have two separate problems: "is the prose
 natural" and "does the structure have the right amount of information".
-`tech-writer` specializes in the latter and delegates the former
-(sentence-level naturalness, reading load, terminology, and removing
-"AI smell") to a prose-polishing skill such as
-[natural-japanese](https://github.com/coji/natural-japanese). With both
-installed, kotonoha locks the structure and technical invariants, invokes the
-Japanese prose pass, then rechecks the structure before rubber-duck review.
+Kotonoha includes both layers. `tech-writer` owns structure and completeness;
+the original bundled `japanese-prose` skill uses
+[GiNZA](https://github.com/megagonlabs/ginza) to check sentence-level
+naturalness, reading load, terminology, dependency depth, and repeated
+AI-like patterns. Kotonoha locks the structure and technical invariants, runs
+the Japanese prose pass, then rechecks the structure before rubber-duck
+review.
 
 ## What it does
 
+- Structure ambiguous business and technical problems with issue trees,
+  hypotheses, evidence ledgers, Current–Target–Gap analysis, transparent
+  decision matrices, and Pyramid Principle synthesis
 - Create/review README, design docs/ADRs, API reference, PR
   descriptions/commit messages/issue reports, release notes, user manuals,
   code comments, requirements definitions, system designs, test plans,
   operations runbooks, migration plans, security designs, technical proposals,
-  RFI/RFP procurement documents, and Qiita/Zenn articles
+  Blueprints, White Papers, RFI/RFP procurement documents, and Qiita/Zenn
+  articles
 - Doctype-specific structure and checklists to guide writing
-- Optional `natural-japanese` integration for Japanese phrase lint,
-  reading-load review, terminology checks, and iterative prose optimization
-  without changing IDs, facts, tables, code, or acceptance criteria
+- Original GiNZA-based `japanese-prose` lint, reading-load review, terminology
+  checks, and iterative prose optimization without changing IDs, facts,
+  tables, code, or acceptance criteria
 - Iterative rubber-duck review after document creation, with fixes and
   re-review until no actionable findings remain; unavailable reviews are
   reported as `review not performed`, while unresolved review loops are
@@ -64,6 +91,8 @@ Japanese prose pass, then rechecks the structure before rubber-duck review.
 | User guidance | User manual, how-to guide, tutorial | `user-manual` |
 | Source documentation | Code comments, docstrings | `code-comments` |
 | Internal technical proposal | Architecture, investment, and delivery proposal | `technical-proposal` |
+| Future-state blueprint | Business, operating-model, data, and technology transformation blueprint | `blueprint` |
+| Evidence-led publication | Technical or business White Paper | `white-paper` |
 | Request for information | RFI | `rfi` |
 | Request for proposal | RFP | `rfp` |
 | Technical article | Zenn article | `zenn` |
@@ -72,10 +101,41 @@ Japanese prose pass, then rechecks the structure before rubber-duck review.
 Reusable templates are included for README, design decisions, user manuals,
 PR descriptions, requirements definitions, system designs, test plans,
 operations runbooks, migration plans, security designs, technical proposals,
-RFI, RFP, and Qiita articles. Every supported doctype includes dedicated
-structure guidance and a review checklist under
+Blueprints, White Papers, RFI, RFP, and Qiita articles. Every supported
+doctype includes dedicated structure guidance and a review checklist under
 `skills/tech-writer/references/doctypes/`.
 
+## What consulting-analyst does
+
+- Defines the decision-maker, decision question, outcome, scope, and evidence
+  gaps before a document or presentation is written
+- Selects the smallest useful framework set instead of filling frameworks
+  mechanically
+- Builds an issue tree and testable hypothesis/evidence ledger
+- Supports Current–Target–Gap analysis and weighted option comparison with
+  scoring anchors and sensitivity analysis
+- Separates facts, estimates, assumptions, interpretations, and
+  recommendations
+- Produces a traceable synthesis handoff for `tech-writer` and
+  `presentation-planner`
+
+Example requests:
+
+```text
+Structure this business problem as an issue tree and identify the evidence
+needed to answer each priority issue.
+```
+
+```text
+Analyze the current and target states, identify the gaps, and prepare the
+analysis for a Blueprint.
+```
+
+```text
+Compare these alternatives using explicit criteria and prepare a White Paper
+handoff without inventing missing evidence.
+```
+
 ## What presentation-planner does
 
 - Defines the audience, decision, call to action, and presentation constraints
@@ -94,10 +154,10 @@ structure guidance and a review checklist under
 ### Prerequisites
 
 - GitHub Copilot CLI installed
-- Python 3.9+ if you want to run the lint script (standard library only,
-  no extra install needed)
-- `uv` when using `natural-japanese` diagnostics such as phrase lint,
-  reading-load analysis, outline extraction, and terminology checks
+- Python 3.9+ for tech-writer's structural lint
+- Python 3.10+ and `uv` for the bundled GiNZA diagnostics such as prose lint,
+  reading-load analysis, outline extraction, and terminology checks; `uv`
+  resolves GiNZA, `ja_ginza`, and spaCy on first use
 
 ### Install from npm
 
@@ -109,11 +169,11 @@ npm install --save-dev kotonoha
 npx kotonoha install
 ```
 
-### Install tech-writer and presentation-planner together
+### Install all bundled skills together
 
 `kotonoha install` installs every packaged skill that is not already present.
-The following commands install both `tech-writer` and
-`presentation-planner` into `.github/skills/`:
+The following commands install `consulting-analyst`, `tech-writer`,
+`japanese-prose`, and `presentation-planner` into `.github/skills/`:
 
 ```bash
 npm install --save-dev kotonoha
@@ -121,45 +181,68 @@ npx kotonoha install --skill all
 ```
 
 `--skill all` is the default, so `npx kotonoha install` has the same behavior.
-Confirm that both skills were installed:
+Confirm that all four skills were installed:
 
 ```bash
+test -f .github/skills/consulting-analyst/SKILL.md
 test -f .github/skills/tech-writer/SKILL.md
+test -f .github/skills/japanese-prose/SKILL.md
 test -f .github/skills/presentation-planner/SKILL.md
 ```
 
-If either directory already exists, the default command preserves it and
-installs only the missing skill. To replace and update both installed skills
-at once, review or back up local customizations first, then run:
+If a directory already exists, the default command preserves it and installs
+only the missing skills. To replace and update all installed skills at once,
+review or back up local customizations first, then run:
 
 ```bash
 npx kotonoha install --skill all --force
 ```
 
-For Japanese sentence-level optimization, also install
-`natural-japanese` using one of its supported installation methods:
+### Built-in Japanese prose optimization
 
-```bash
-npx skills add coji/natural-japanese
+Kotonoha includes its own `japanese-prose` skill, so no separate prose skill
+installation is required. `npx kotonoha install` places it beside
+`tech-writer`, allowing the writing workflow to run GiNZA-based prose lint,
+reading-load checks, terminology extraction, outline inspection, and
+iterative prose review locally. The implementation was developed from
+scratch for kotonoha and does not include `natural-japanese` source code.
+GiNZA dependency and license information is recorded in
+`skills/japanese-prose/NOTICE.md`.
+
+You do not need to name GiNZA explicitly in a natural-language request.
+Requests to make a Japanese document more natural, readable, concise, or less
+formulaic invoke the bundled prose-optimization workflow. For example:
+
+```text
+Rewrite README-ja.md in natural, readable Japanese.
 ```
 
-Ensure the installed skill is visible to Copilot CLI in the same registered
-skill root used by this project, such as
-`.github/skills/natural-japanese` or
-`~/.copilot/skills/natural-japanese`. If the command installs it for a
-different host, follow the upstream alternative installation instructions
-and place or link the skill into a Copilot-visible skill directory.
+```text
+Review this design document for unnatural Japanese, overly long sentences,
+and repetitive AI-like phrasing, then fix the findings.
+```
+
+You can specify the intended mode more precisely:
+
+- Edit the file: `Optimize the Japanese prose in README-ja.md.`
+- Review without editing: `Review the Japanese in README-ja.md, but do not modify the file.`
+- Score only: `Score the Japanese prose in README-ja.md out of 100.`
+- Run every diagnostic: `Run the full Japanese prose optimization workflow on README-ja.md.`
+- Request GiNZA explicitly: `Analyze README-ja.md with GiNZA and improve dependency depth and reading load.`
 
-If no compatible Japanese prose-polishing skill is registered, kotonoha
-finishes the structural workflow and reports
-`Japanese prose optimization not performed` instead of claiming that the
-prose was optimized.
+When creating a new Japanese document, asking `Create a Japanese README for
+this repository` lets `tech-writer` create and structurally review the draft,
+then run the GiNZA-based prose pass before rubber-duck review. To require the
+pass unambiguously, ask: `Create or revise <file> as a technical document and
+run GiNZA-based Japanese prose optimization.`
 
-The default destinations are `.github/skills/tech-writer` and
-`.github/skills/presentation-planner` in the current project. To install
-only one skill, or use another supported skill directory:
+The default destinations are `.github/skills/consulting-analyst`,
+`.github/skills/tech-writer`, `.github/skills/japanese-prose`, and
+`.github/skills/presentation-planner` in the current project. To install only
+one skill, or use another supported skill directory:
 
 ```bash
+npx kotonoha install --skill consulting-analyst
 npx kotonoha install --skill presentation-planner
 npx kotonoha install --target .claude/skills
 npx kotonoha install --target ~/.copilot/skills
@@ -180,6 +263,8 @@ installation safe:
 ```bash
 npx kotonoha install
 # Skipped tech-writer (...)
+# Installed consulting-analyst (...)
+# Installed japanese-prose (...)
 # Installed presentation-planner (...)
 ```
 
@@ -211,7 +296,9 @@ npx kotonoha install --force
 To update only one skill:
 
 ```bash
+npx kotonoha install --skill consulting-analyst --force
 npx kotonoha install --skill tech-writer --force
+npx kotonoha install --skill japanese-prose --force
 npx kotonoha install --skill presentation-planner --force
 ```
 
@@ -243,7 +330,9 @@ into that repository's `.github/skills/`, `.claude/skills/`, or your global
 `~/.copilot/skills/`.
 
 ```bash
+cp -r skills/consulting-analyst /path/to/your-repo/.github/skills/consulting-analyst
 cp -r skills/tech-writer /path/to/your-repo/.github/skills/tech-writer
+cp -r skills/japanese-prose /path/to/your-repo/.github/skills/japanese-prose
 cp -r skills/presentation-planner /path/to/your-repo/.github/skills/presentation-planner
 ```
 
@@ -271,27 +360,40 @@ works too (standard library only).
 ## Repository layout
 
 ```text
+skills/consulting-analyst/   # problem structuring and evidence-led analysis skill
+  SKILL.md                   # analysis workflow, safeguards, and handoff
+  references/                # framework selection, evidence discipline, handoff contract
+  assets/templates/          # brief, issue tree, evidence, decision, and synthesis artifacts
 skills/tech-writer/          # the skill itself
   SKILL.md                   # skill definition
   references/                # structure constitution + doctype rules/checklists
-  references/doctypes/       # README, requirements/design/test/operations/migration/security, API docs, PR/issue, release notes, proposals, RFI/RFP, Qiita/Zenn
+  references/doctypes/       # README, requirements/design/test/operations/migration/security, API docs, PR/issue, release notes, proposals, Blueprints, White Papers, RFI/RFP, Qiita/Zenn
   scripts/lint.py            # structural lint script
-  assets/templates/          # doctype skeletons including requirements, design, test, operations, migration, security, and procurement
+  assets/templates/          # doctype skeletons including requirements, design, test, operations, migration, security, strategy, evidence-led publications, and procurement
+skills/japanese-prose/       # original GiNZA-based prose optimization skill
+  SKILL.md                   # writing, lint, review, and convergence workflow
+  references/                # writing guidelines, review workflow, and scoring
+  scripts/                   # prose lint, reading-load, outline, and terminology diagnostics
+  NOTICE.md                  # GiNZA dependency and license information
 skills/presentation-planner/ # storyline, design-spec, and PPTX handoff skill
   SKILL.md
   references/                # boundary, scenario/design guidance, customization, handoff contract
   assets/scenario-templates/ # executive, technical, and data-report narrative scenarios
   assets/design-templates/   # executive, technical, and data-report YAML designs
 .github/skills/tech-writer   # symlink to skills/tech-writer (where Copilot CLI reads it)
+.github/skills/consulting-analyst
+.github/skills/japanese-prose
 .github/skills/presentation-planner
 ```
 
 ## Known limitations
 
-- `scripts/lint.py` only detects structural issues (headings, code blocks,
-  placeholders, links); it does not detect prose naturalness, vocabulary,
-  or rhythm by itself. Those checks require a registered prose-polishing
-  skill such as `natural-japanese`.
+- `consulting-analyst` structures supplied or verified evidence but does not
+  manufacture market data, customer facts, estimates, or citations.
+- `skills/tech-writer/scripts/lint.py` detects structural and Markdown
+  rendering issues. Prose naturalness, vocabulary, rhythm, and reading load
+  are handled by the separately invoked but bundled
+  `skills/japanese-prose` workflow and GiNZA diagnostics.
 - The doctypes are written mainly with Japanese technical-writing
   conventions in mind; most of the guidance (especially the commit-message
   imperative-mood rule) applies directly to English documents as well.
@@ -302,10 +404,10 @@ skills/presentation-planner/ # storyline, design-spec, and PPTX handoff skill
 
 ## Acknowledgment
 
-- [natural-japanese](https://github.com/coji/natural-japanese) (MIT
-  License) — the design principle "machines detect, humans (or agents)
-  judge" and "prevent at generation time rather than fix afterward"
-  informed this project's design.
+- [GiNZA](https://github.com/megagonlabs/ginza) (MIT License) — provides
+  tokenization, part-of-speech tagging, dependency parsing, lemmatization,
+  sentence boundaries, and named-entity recognition for kotonoha's original
+  Japanese prose diagnostics.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kotonoha",
-  "version": "0.1.6-dev.0",
-  "description": "GitHub Copilot CLI skills for technical writing and PPTX presentation planning.",
+  "version": "0.3.0",
+  "description": "GitHub Copilot CLI skills for consulting analysis, technical writing, Japanese prose, and PPTX planning.",
   "license": "MIT",
   "author": "nahisaho",
   "repository": {
@@ -16,7 +16,8 @@
     "kotonoha": "bin/kotonoha.js"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:ginza": "uv run skills/japanese-prose/scripts/test_engine.py"
   },
   "engines": {
     "node": ">=18"
@@ -26,6 +27,9 @@
     "github-copilot",
     "skill",
     "technical-writing",
+    "consulting",
+    "analysis",
+    "strategy",
     "documentation",
     "markdown",
     "presentation",
@@ -35,7 +39,10 @@
   ],
   "files": [
     "CHANGELOG.md",
+    "README-ja.md",
     "bin/",
-    "skills/"
+    "skills/",
+    "!skills/**/__pycache__/",
+    "!skills/**/*.pyc"
   ]
 }

package/skills/consulting-analyst/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: consulting-analyst
+description: >-
+  Structures ambiguous business and technical problems before writing or
+  presentation design. Uses consulting frameworks selectively—not
+  mechanically—to define the decision question, build issue trees, form and
+  test hypotheses, compare current and target states, evaluate alternatives,
+  and synthesize evidence into an actionable recommendation. Use for requests
+  like "structure this problem", "build an issue tree", "analyze the root
+  cause", "compare these options", "create a transformation roadmap",
+  "prepare the analysis for a Blueprint or White Paper",
+  「課題を構造化して」「論点を整理して」「仮説を検証して」
+  「現状と目標のGapを分析して」「選択肢を比較して」
+  「BlueprintやWhite Paperの分析を準備して」. Produces analysis artifacts
+  and handoff inputs for tech-writer and presentation-planner. Does not own
+  final document prose, slide design, implementation design, or factual
+  research that has not been supplied or independently verified.
+license: MIT
+argument-hint: "[analyze|review|handoff] <problem, decision, or source files>"
+---
+
+# consulting-analyst
+
+Turns an ambiguous problem into a defensible chain from question to evidence,
+conclusion, and action. Frameworks are tools for reducing uncertainty, not
+formats that must be filled.
+
+## Responsibility boundary
+
+This skill owns:
+
+- Decision-question and success-condition definition
+- Issue decomposition and MECE review
+- Hypotheses, evidence needs, confidence, and falsification conditions
+- Current-state, target-state, and gap analysis
+- Explicit option criteria, weighting, scoring, and sensitivity analysis
+- Synthesis into findings, implications, recommendations, and next actions
+- Structured handoff to `tech-writer` or `presentation-planner`
+
+This skill does not:
+
+- Invent facts, customer evidence, market data, estimates, or citations
+- Treat assumptions as verified findings
+- Write the final technical document when `tech-writer` is available
+- Design slide narratives or visual systems when `presentation-planner` is
+  available
+- Replace requirements, system design, project planning, financial modeling,
+  legal review, or domain-expert judgment
+
+When the user asks directly for a Blueprint, White Paper, proposal, or
+presentation and the underlying analysis is incomplete, complete this
+analysis pass first, then hand the result to the owning writing or
+presentation skill.
+
+## Modes
+
+- `analyze` (default): create or revise the analysis artifacts and produce a
+  synthesis handoff.
+- `review`: challenge an existing analysis for missing branches, unsupported
+  claims, hidden assumptions, biased criteria, weak evidence, and conclusions
+  that do not follow.
+- `handoff`: normalize existing analysis into the handoff contract without
+  repeating completed work.
+
+## 1. Gather context one question at a time
+
+Ask only the single most informative missing question, then wait. Stop when
+the following are known or explicitly recorded as unknown:
+
+1. The decision-maker or actor who will use the analysis
+2. The exact decision, problem, or question to resolve
+3. The measurable outcome or decision deadline
+4. Scope, constraints, and excluded topics
+5. Available evidence, source files, and known data gaps
+6. Required destination: analysis only, document, Blueprint, White Paper,
+   proposal, or presentation
+
+Do not ask the user which framework to use unless they have a mandatory
+method. Select the smallest framework set that resolves the question.
+
+## 2. Create the analysis workspace
+
+Write artifacts under `.consulting/<analysis-slug>/` unless the user specifies
+another directory. Use a stable, filesystem-safe slug so separate analyses do
+not overwrite one another.
+
+In `analyze` mode, create:
+
+1. `analysis-brief.md`
+2. `issue-tree.md`
+3. `hypothesis-evidence-ledger.md`
+4. `synthesis-handoff.md`
+
+Start from the matching files under `assets/templates/`.
+The packaged templates use English canonical field names. Translate headings
+and instructions into the requested output language while preserving artifact
+filenames, IDs, statement types, status values, and table semantics.
+
+Create `decision-analysis.md` only when Current–Target–Gap analysis or option
+comparison is in scope. Record omitted artifacts and the reason in
+`synthesis-handoff.md`. In `review` mode, update only artifacts affected by
+the findings. In `handoff` mode, normalize the supplied analysis without
+creating empty framework artifacts.
+
+## 3. Select frameworks by decision need
+
+Read `references/framework-selection.md`. Use no more than three primary
+frameworks in one analysis unless the user explicitly requests a broader
+study.
+
+| Decision need | Primary framework |
+|---|---|
+| Decompose an ambiguous question | Issue Tree / logic tree |
+| Test an explanation or proposed answer | Hypothesis–Evidence–Falsification |
+| Explain cause rather than symptoms | Causal tree / 5 Whys with evidence |
+| Define a future state and transformation path | Current–Target–Gap |
+| Compare alternatives transparently | Weighted decision matrix |
+| Communicate the final reasoning | Pyramid Principle / SCQA |
+
+SWOT, 3C, PESTLE, Five Forces, capability maps, and impact/effort matrices
+may be supporting lenses. Do not use them unless each field changes a
+decision, hypothesis, criterion, or action.
+
+## 4. Build a testable issue tree
+
+Use `references/evidence-and-hypotheses.md`.
+
+1. Write one decision question at the root.
+2. Decompose by one explicit logic at each level, such as causes, options,
+   capabilities, lifecycle stages, or economics.
+3. Make sibling branches collectively sufficient for the parent question and
+   remove material overlap.
+4. Mark branches as `priority`, `supporting`, `out of scope`, or `unknown`.
+5. Define what evidence would answer every priority leaf.
+
+Do not claim perfect MECE when the domain is uncertain. Record residual
+overlap and known omissions.
+
+## 5. Form hypotheses and manage evidence
+
+For each priority issue:
+
+- State the hypothesis as a falsifiable proposition
+- Record why it is plausible without presenting that rationale as proof
+- Define evidence that supports and weakens it
+- Identify source, date, owner, and confidence
+- Separate `fact`, `estimate`, `assumption`, `interpretation`, and
+  `recommendation`
+- Set the next evidence-gathering action and owner
+
+Never upgrade an assumption to a finding because it appears in several
+frameworks. Repetition is not corroboration.
+
+## 6. Analyze gaps or alternatives
+
+Use the path that fits the decision:
+
+### Current–Target–Gap
+
+Describe current and target states with the same dimensions and evidence
+standard. Map each material gap to an intervention, dependency, owner,
+measure, and transition risk. Do not jump directly from aspiration to a
+roadmap.
+
+### Weighted decision matrix
+
+Define criteria before scoring options. State:
+
+- Criterion definition and direction
+- Weight and rationale
+- Scoring scale with anchors
+- Evidence behind each score
+- Mandatory thresholds or disqualifiers
+- Sensitivity to plausible changes in weights or scores
+
+The arithmetic supports judgment; it does not replace it.
+
+## 7. Synthesize without overclaiming
+
+Build the synthesis in this order:
+
+1. **Answer**: the current best answer to the decision question
+2. **Because**: two to four mutually distinct supporting findings
+3. **Evidence**: traceable sources and confidence for each finding
+4. **So what**: implication for the decision-maker
+5. **Now what**: action, owner, timing, and validation checkpoint
+6. **Uncertainty**: assumptions, counterevidence, and conditions that would
+   change the recommendation
+
+Use the Pyramid Principle for the final reasoning structure. Use SCQA only
+when it clarifies the audience's path to the question; do not manufacture
+dramatic tension.
+
+## 8. Handoff to the owning skill
+
+Read `references/handoff-contract.md`.
+
+- For a technical or business document, pass `synthesis-handoff.md` to
+  `tech-writer`, including the target doctype.
+- For a presentation, pass it to `presentation-planner`, including the exact
+  audience decision and evidence status.
+- When both are requested, write the source document first unless the user
+  explicitly prioritizes the presentation.
+
+The receiving skill may restructure the communication, but it must preserve
+evidence IDs, confidence, assumptions, disconfirming evidence, decision
+criteria, and unresolved questions.
+
+## 9. Quality gate
+
+Before reporting completion, confirm:
+
+- The root question names an actor and decision
+- Every recommendation traces to findings and evidence
+- Every priority issue has an answer, explicit unknown, or next action
+- Facts, estimates, assumptions, and interpretations remain distinguishable
+- A hypothesis marked `Supported` cites at least one `Fact` or `Estimate`;
+  that evidence must support the specific hypothesis. Assumptions and
+  interpretations may guide analysis but never count as supporting evidence
+- Criteria and weights were defined before option scoring
+- Decision-matrix weights sum to 100%, and sensitivity checks follow the
+  minimum procedure in `decision-analysis.md`
+- Current and target states use comparable dimensions
+- Counterevidence and uncertainty are visible
+- No framework section exists only because a template contained it
+- Every omitted artifact is named with the reason it was unnecessary
+- The handoff identifies what the next skill may and may not change
+
+If evidence is insufficient, report `analysis incomplete` with the unresolved
+decision-critical gaps. Do not create a success-shaped recommendation.
+
+## Completion report
+
+Report:
+
+- Mode and selected frameworks with reasons
+- Artifacts created or reviewed
+- Decision question and current answer
+- Confirmed findings, assumptions, and unresolved evidence gaps
+- Handoff destination, if any
+- `analysis completed` or `analysis incomplete`