jupytermind 0.3.0

package/.github/skills/tech-writer/references/doctypes/technical-proposal.md

@@ -0,0 +1,49 @@
+# Technical proposal type
+
+A technical proposal asks decision-makers to approve a technical approach,
+budget, and delivery plan. It is broader than an ADR: it must connect the
+architecture to measurable outcomes, implementation cost, risks, and a
+recorded decision.
+
+This doctype is for an internal approval proposal. For a supplier's
+technical bid in response to an RFP, structure the response against the
+RFP's requirement IDs, requested proposal contents, pricing, and contract
+deviations instead of using this template.
+
+## Target reader
+
+The person or group accountable for approving the investment, accepting the
+trade-offs, and assigning implementation ownership.
+
+## Settle before writing
+
+- The exact decision or approval being requested
+- The current problem and measurable target outcome
+- Budget, deadline, security, compliance, and staffing constraints
+- At least one alternative, including the current-state baseline
+- The evaluation period used for total cost of ownership
+
+## Template
+
+Start from `assets/templates/technical-proposal.md`.
+The template is the Japanese-language skeleton; translate its headings when
+the target document is English.
+
+## Recommended skeleton
+
+1. Decision requested and executive summary
+2. Background, measurable goals, and non-goals
+3. Proposed architecture, data, and security
+4. Delivery, rollout, rollback, cost, and staffing
+5. Alternatives using shared cost, time, effort, and risk axes
+6. Risks, success metrics, unresolved questions, and decision record
+
+## Checklist
+
+- [ ] Is the requested decision stated before the implementation detail?
+- [ ] Are goals measurable, with an action if a target is missed?
+- [ ] Are non-goals, assumptions, and constraints explicit?
+- [ ] Does the comparison include a current-state baseline and shared axes?
+- [ ] Are initial cost, annual recurring cost, and TCO period comparable?
+- [ ] Are rollout, rollback, security, risks, and ownership covered?
+- [ ] Can the final approver, date, and decision be recorded in the document?

package/.github/skills/tech-writer/references/doctypes/test-plan.md

@@ -0,0 +1,67 @@
+# Test plan type
+
+A test plan defines how requirements and quality risks will be verified,
+which environments and data are needed, and what evidence permits a release
+or acceptance decision. It covers planning and traceability rather than
+replacing executable test code.
+
+## Target reader
+
+Test leads, developers, product owners, business acceptance testers,
+operators, security reviewers, and release approvers.
+
+## Settle before writing
+
+- The approved requirements and design baselines
+- The approved security-design baseline and security test IDs, when present
+- In-scope systems, environments, platforms, and quality attributes
+- The highest-impact quality risks and required test levels
+- Measurable entry, exit, and release criteria
+- Environment, data, tooling, staffing, and schedule constraints
+- Defect severity definitions and residual-risk approval authority
+
+## Responsibility boundary
+
+Define the verification strategy, cases, criteria, ownership, and evidence.
+Keep detailed automation implementation in test code. A test plan must not
+weaken an approved acceptance criterion; record conflicts as open issues and
+resolve them through requirement change control.
+
+The test section in `system-design` is sufficient while verification remains
+an integrated design summary. Use a standalone `test-plan` when execution
+needs its own environments, schedule, evidence, release gates, or approvers.
+When both exist, the test plan is authoritative for test execution and
+release evidence, while the system design retains the architectural rationale.
+When a `security-design` exists, import its security test, threat, and control
+IDs. Preserve `SEC-TC-*` as the planned security-test identity and map it to
+the executable `TC-*` case that produces release evidence.
+
+## Template
+
+Start from `assets/templates/test-plan.md`.
+The template is the Japanese-language skeleton; translate its headings when
+the target document is English.
+
+## Recommended skeleton
+
+1. Agreement target, baselines, scope, quality goals, and risks
+2. Test levels, non-functional testing, environment, and data
+3. Entry, exit, release, and residual-risk criteria
+4. Requirement-to-test traceability and defect management
+5. Schedule, ownership, evidence, risks, and approval
+
+## Checklist
+
+- [ ] Are the requirement and design baselines uniquely identified?
+- [ ] Are scope, exclusions, environments, platforms, data, and production
+      differences explicit?
+- [ ] Does the strategy prioritize tests using concrete quality risks?
+- [ ] Are functional and non-functional criteria measurable?
+- [ ] Can every Must requirement and acceptance condition be traced to tests?
+- [ ] Can every applicable security test, threat, and control be traced from
+      the security design to an executable case and its evidence?
+- [ ] Are entry, exit, defect, release, and residual-risk criteria objective?
+- [ ] Are suspension and resumption conditions defined for blocked or invalid
+      test cycles?
+- [ ] Are evidence storage, ownership, schedule, and approval defined?
+- [ ] Are test-data privacy, cleanup, and environment reset covered?

package/.github/skills/tech-writer/references/doctypes/user-manual.md

@@ -0,0 +1,58 @@
+# User manual / how-to guide / tutorial type
+
+For this doctype, quality is almost entirely determined by "can the reader
+actually reproduce this by following it", so apply it more strictly than
+the other types.
+
+## Target reader
+
+Someone using the target product/feature for the first time, or after a
+long gap. Assume thin prior knowledge of jargon.
+
+## Settle before writing
+
+1. **Floor of prior knowledge**: state up front "this guide assumes you
+   already know X". Without it, the reader pays a recurring cost of
+   deciding whether they're the intended audience.
+2. **Completion condition**: at the end of the steps, state what "success"
+   looks like in a verifiable form (a screen shown, a value returned, a
+   file produced).
+
+## Recommended skeleton
+
+1. **What this guide gets you**: the first three lines (rule 1 of the
+   structure constitution).
+2. **Prerequisites**: required permissions, installed software, versions.
+   A separate section, before the steps.
+3. **Steps**: one action per numbered step (rule 4). Each step has three
+   parts:
+   - the action to take (command/click target)
+   - how the screen/output changes afterward (so the reader can
+     self-verify they're on track)
+   - any tricky branch point, noted right there (not collected at the end)
+4. **Completion check**: a concrete way to verify "if you see this,
+   you've succeeded".
+5. **Troubleshooting**: symptom → cause → fix, as a table. Avoid phrasing
+   that just offloads the problem to the reader, like "if you see an
+   error, contact your administrator".
+
+## Tutorial-specific notes
+
+- A tutorial's goal is "one success experience via the shortest path", not
+  exhaustive coverage. Move advanced options to a "further reading"
+  section instead of lengthening the main steps.
+- Placing a verification point (screenshot, expected output sample) right
+  after each step lets the reader proceed without doubt.
+
+## Checklist
+
+- [ ] Are prerequisites (permissions/environment/pre-installs) stated in
+      their own section before the steps?
+- [ ] Is each step a single action, with information to confirm the state
+      change after executing it?
+- [ ] Is the completion condition stated in a verifiable form (screen,
+      output, artifact)?
+- [ ] Is troubleshooting in "symptom → cause → fix" form, without
+      offloading action entirely to the reader?
+- [ ] Is jargon given a brief explanation on first use (relative to the
+      target reader's prior knowledge)?

package/.github/skills/tech-writer/references/doctypes/white-paper.md

@@ -0,0 +1,84 @@
+# White Paper type
+
+A White Paper helps a defined audience understand a consequential problem,
+evaluate evidence, and reach an informed conclusion. It may explain an
+emerging topic, establish a point of view, or describe a solution pattern,
+but it must distinguish evidence from interpretation and must not disguise
+marketing claims as independent analysis.
+
+## Target reader
+
+Decision-makers, practitioners, evaluators, customers, partners, regulators,
+or industry readers who need a credible explanation and a defensible basis
+for action.
+
+## Settle before writing
+
+- The reader's decision, question, or misconception the paper addresses
+- The central claim and what evidence could weaken or disprove it
+- The publication scope, date boundary, geography, and intended longevity
+- The research method and acceptable source quality
+- The publisher's relationship to products, services, sponsors, or cited data
+- The desired next action, without overstating certainty
+
+## Responsibility boundary
+
+A White Paper explains and supports a position. It is not a requirements
+specification, implementation design, sales brochure, academic paper, or
+contractual promise. Product examples may illustrate a finding, but factual
+claims, estimates, customer outcomes, and recommendations must remain
+traceable to named evidence and limitations.
+
+Use `technical-proposal` for an internal approval request, `blueprint` for a
+future state and transformation roadmap, and `white-paper` for an
+evidence-led public or stakeholder-facing argument.
+
+## Template
+
+Start from `assets/templates/white-paper.md`.
+The template is the Japanese-language skeleton; translate its headings when
+the target document is English.
+
+## Recommended skeleton
+
+1. Title, abstract, target reader, central claim, and disclosure
+2. Problem definition, scope, terminology, and research method
+3. Evidence-led findings with confidence and limitations
+4. Options, solution pattern, recommendation, and adoption considerations
+5. Counterarguments, risks, boundaries, and conclusion
+6. References, evidence ledger, glossary, authorship, and revision history
+
+## Checklist
+
+- [ ] Does the abstract state the problem, conclusion, audience, and practical
+      consequence?
+- [ ] Is `Analysis status: Completed / Incomplete / Not performed` recorded
+      separately from publication status, with `Evidence gaps` and the analysis
+      handoff location (or none)?
+- [ ] For `Incomplete`, are evidence gaps and confidence visible and every
+      affected conclusion or recommendation expressed with conditional wording,
+      or returned to consulting-analyst? For `Not performed`, are the scope and
+      reason explicit without implying completed analysis?
+- [ ] Is the central claim specific enough to challenge with evidence?
+- [ ] Are facts, estimates, interpretations, and recommendations visibly
+      distinguished?
+- [ ] Does every consequential claim link to a source or evidence identifier?
+- [ ] Does the evidence ledger keep SRC source records separate from EVD analysis
+      evidence, preserving their IDs and meaning?
+- [ ] Do claims and findings link relevant HYP / FND / EVD IDs from the handoff,
+      marking inapplicable links `N/A` with a reason without forcing consulting
+      IDs when no consulting handoff exists?
+- [ ] Are interpretations preserved without counting as supporting evidence,
+      with `Supported` hypotheses backed by relevant Fact / Estimate evidence?
+- [ ] Are source date, scope, method, sample, and limitations available?
+- [ ] Are contradictory evidence and credible alternatives addressed?
+- [ ] Are product, sponsor, author, and data-source relationships disclosed?
+- [ ] Are publication approval and legal, compliance, and claims reviews
+      recorded, including approval to use customer names and quantitative
+      claims?
+- [ ] Does `Approved for Publication` match a complete approval record, with
+      a reason recorded for every review marked not applicable?
+- [ ] Are case studies labeled and prevented from implying universal results?
+- [ ] Does the recommendation state where it does not apply?
+- [ ] Can readers reproduce the source trail and identify the document's
+      publication and revision dates?

package/.github/skills/tech-writer/references/doctypes/zenn.md

@@ -0,0 +1,66 @@
+# Zenn article type
+
+For this platform, the title lives in YAML frontmatter, not an in-body
+heading, and readers decide whether to keep reading within the first
+screen — apply rule 1 of the structure constitution to the frontmatter
+`title` plus the lead paragraph together, not to an in-body '#'.
+
+## Target reader
+
+A developer scanning Zenn's feed or search results, deciding in a few
+seconds whether this article solves their problem right now.
+
+## Format
+
+Markdown, with Zenn's frontmatter and a few platform-specific extensions
+on top of GFM. No in-body '#' heading for the article title — sections
+start at '##'.
+
+## Recommended frontmatter
+
+```yaml
+---
+title: "<Article title>"
+emoji: "<One emoji representing the article>"
+type: "tech" # "tech" for a technical explanation, "idea" for an opinion/experience piece
+topics: ["<1-5 lowercase topics>"]
+published: false # flip to true only when ready to publish
+---
+```
+
+- `title`, `emoji`, `type`, `topics`, `published` are all required by Zenn;
+  a missing or malformed field can silently block publishing.
+- Pick `type: "tech"` vs `"idea"` deliberately — it changes how the
+  article is categorized and discovered, not just a label.
+
+## Recommended skeleton
+
+1. **Lead paragraph (right after frontmatter, before any heading)**: what
+   this article gets the reader, and why now — this is rule 1's "first
+   three lines", since there's no in-body title to carry it.
+2. **Prerequisites** (if applicable): versions, environment, prior
+   knowledge assumed, before any steps.
+3. **Body sections, one concern per `##` heading**: order them the way the
+   reader would naturally need the information (rule 3).
+4. **Code blocks with both a language tag and, where relevant, a filename**:
+   Zenn supports ` ```js:example.js ` — prefer this over a bare language
+   tag when the file identity matters to the reader.
+5. **`:::message` / `:::message alert` boxes for asides**: use these for
+   genuinely non-obvious caveats or warnings, not routine notes — overuse
+   dilutes their signal.
+6. **Closing summary or "next steps" section** (if the article is long):
+   what the reader should now be able to do, echoing the lead paragraph's
+   promise.
+
+## Checklist
+
+- [ ] Are all five required frontmatter fields present and non-empty
+      (`title`, `emoji`, `type`, `topics`, `published`)?
+- [ ] Does the lead paragraph right after frontmatter state what this
+      article gets the reader, since there's no in-body title to do that?
+- [ ] Is `type` ("tech" vs "idea") a deliberate choice, not a default left
+      unconsidered?
+- [ ] Do code blocks carry a language tag (and a filename where the file
+      identity matters)?
+- [ ] Are `:::message` boxes reserved for genuinely non-obvious asides
+      rather than routine notes?

package/.github/skills/tech-writer/references/japanese-prose-optimization.md

@@ -0,0 +1,110 @@
+# Japanese prose optimization handoff
+
+Use this pass after a Japanese document's structure and required information
+are complete. The goal is to remove mechanical or translated-sounding prose
+without changing the document's approved meaning, obligations, evidence, or
+traceability.
+
+The optimizer is kotonoha's original bundled `japanese-prose` skill.
+Kotonoha owns document structure and completeness; `japanese-prose` owns
+sentence-level clarity, rhythm, word choice, reading load, terminology, and
+detection of repeated AI-like phrasing through GiNZA analysis.
+
+## Run this pass when
+
+- The requested final language is Japanese, including a bilingual document
+  whose audience-facing prose is primarily Japanese.
+- The task is `write` mode.
+- The artifact is a living, multi-section document.
+- The bundled `japanese-prose` skill is readable.
+
+Skip it for English documents, generated machine-readable files, and source
+code. Also skip atomic artifacts such as commit messages, PR descriptions,
+issue reports, single release-note entries, and code comments/docstrings
+unless the user explicitly requests prose polishing and supplies the prose in
+a standalone file. For in-scope mixed-language documents, optimize only
+Japanese prose.
+
+## Freeze these invariants
+
+Give the prose optimizer the target file, doctype, reader, and intended
+outcome. Require it to preserve:
+
+- Heading hierarchy, section order, and doctype-required sections
+- Requirement, risk, control, test, interface, and decision IDs
+- Numbers, units, dates, proper nouns, citations, URLs, and source mappings
+- Normative force such as Must / Should / May, approval states, and
+  acceptance criteria
+- Tables, code blocks, commands, schemas, frontmatter keys, and placeholders
+- Markdown emphasis spacing: keep ASCII half-width spaces (`U+0020`) between
+  surrounding prose and both sides of `**strong emphasis**` delimiters; never
+  substitute full-width spaces (`U+3000`), tabs, or non-breaking spaces
+- Explicit assumptions, limitations, residual risks, and unresolved items
+
+Heading wording may improve only when its meaning and hierarchy stay intact.
+Never trade technical precision for conversational phrasing.
+
+## Optimization loop
+
+1. Invoke kotonoha's bundled `japanese-prose` through the host's
+   skill-loading mechanism. If the host exposes only skill files, resolve
+   `<tech-writer-dir>/../japanese-prose/SKILL.md` first, then check
+   `.github/skills/japanese-prose/SKILL.md`,
+   `.copilot/skills/japanese-prose/SKILL.md`, and
+   `$HOME/.copilot/skills/japanese-prose/SKILL.md`; expand `$HOME`, load the
+   discovered skill,
+   and follow its workflow.
+2. Ask the loaded skill to review and rewrite only the Japanese prose under
+   the frozen invariants.
+3. Let `<japanese-prose-dir>` be the directory containing the loaded
+   optimizer's `SKILL.md`. When its diagnostics are available, run the
+   optimizer's scripts with their qualified paths:
+
+   ```bash
+   uv run <japanese-prose-dir>/scripts/lint.py <target-file> --genre tech --json > <workdir>/prose-baseline.json
+   uv run <japanese-prose-dir>/scripts/lint.py <target-file> --genre tech --reading-load
+   uv run <japanese-prose-dir>/scripts/outline.py <target-file>
+   uv run <japanese-prose-dir>/scripts/terms.py <target-file>
+   ```
+
+   Do not substitute `skills/tech-writer/scripts/lint.py`; kotonoha's script
+   checks document structure and does not support these prose diagnostics.
+4. Triage findings in context. Do not perform blind global replacements;
+   retain a flagged expression when changing it would weaken precision or
+   alter a defined term.
+5. Re-run the optimizer's rubric and diagnostics after edits. One round is
+   one kotonoha-to-optimizer handoff and its returned edits. Allow at most
+   three rounds per §5 invocation; stop earlier when no actionable prose
+   findings remain. A later rubber-duck edit opens a new invocation limited
+   to the changed Japanese prose. Across the complete write workflow, do not
+   exceed 15 optimizer handoffs.
+6. Compare the optimized document against the frozen invariants. Revert any
+   violating edit, give the violated invariant back to the optimizer, and
+   retry within the round limit. If the violation cannot be resolved, report
+   `Japanese prose optimization did not converge`.
+7. Re-run kotonoha's doctype checklist and structural lint before
+   rubber-duck review.
+
+## Required status
+
+When this pass is in scope (a living, multi-section document whose requested
+final language is Japanese, in `write` mode), report exactly one status:
+
+- `Japanese prose optimization completed`: the registered optimizer ran and
+  no actionable prose findings remain. Run diagnostics when available; if
+  `uv` or a diagnostic script is unavailable, note that limitation without
+  changing this status.
+- `Japanese prose optimization not performed`: the bundled optimizer was
+  missing or unreadable, so no prose review or rewrite ran; include the
+  concrete reason. A standard `npx kotonoha install` should prevent this
+  state.
+- `Japanese prose optimization did not converge`: three rounds completed with
+  unresolved actionable findings or invariant violations, or the optimizer
+  started but failed before producing a valid result, a required
+  post-rubber-duck rerun failed or could not start because all 15 handoffs
+  were already used; list the findings, violations, failure, and attempted
+  fixes.
+
+Do not claim natural-language optimization based only on kotonoha's
+structural lint. Documents outside the scope of this pass require no Japanese
+optimization status.

package/.github/skills/tech-writer/references/style-constitution.md

@@ -0,0 +1,104 @@
+# Technical Document Structure Constitution (8 rules)
+
+Constraints to fix a technical document's *structure* before writing.
+Sentence-level naturalness, vocabulary, and rhythm are out of scope here
+(→ the domain of kotonoha's bundled `japanese-prose` skill).
+
+## Scope: living documents vs. atomic artifacts
+
+These 8 rules assume a **living, multi-section reference document** —
+README, design doc/ADR, API reference, release notes/CHANGELOG file as a
+whole, user manual, requirements definition, system design, test plan,
+operations runbook, migration plan, security design, technical proposal,
+Blueprint, White Paper, RFI/RFP (including a supplier's RFP response), or
+Zenn/Qiita article. Apply all 8 rules to those doctypes. For Zenn and Qiita,
+rule 1's article title lives in YAML frontmatter — see their
+doctype reference files for the platform-specific fields. Zenn body sections
+start at `##`; Qiita body sections start at `#` and use `##` for subsections.
+Every other rule (code examples, disclosed limitations, etc.) still applies
+verbatim.
+
+**Atomic, single-purpose artifacts** — commit messages, PR descriptions,
+issue reports, code comments/docstrings, and a single new entry appended
+to an existing release-notes/CHANGELOG file — have their own skeleton in
+`references/doctypes/pr-commit.md`, `references/doctypes/code-comments.md`,
+and `references/doctypes/release-notes.md` that already encodes the
+equivalent discipline in a form that fits their size (e.g. a PR
+description's What/Why/How opens the same way rule 1 asks a README to; a
+single release-notes entry opens with its version/date heading instead of
+a title-plus-paragraph). Follow that doctype's own skeleton for those
+instead of applying the heading-hierarchy and document-metadata rules
+below verbatim; where the two disagree, the doctype reference wins.
+
+## Markdown emphasis spacing
+
+In generated Markdown, add half-width spaces outside strong-emphasis
+delimiters when they touch surrounding prose. Write
+`これは **強調** になる` rather than `これは**強調**にならない`.
+The spaces are unnecessary at a line boundary or next to punctuation, for
+example `**重要**: 設定を確認する`. Use ASCII spaces (`U+0020`), not
+full-width spaces (`U+3000`), tabs, or non-breaking spaces, immediately before
+and after emphasis embedded in prose. Write `これは **「重要」** と説明する`,
+not `これは　**「重要」**　と説明する`. Never put spaces inside the
+delimiters.
+
+## 1. Say "what this is" and "the outcome" in the first three lines
+
+Readers decide "is this relevant to me" within the first three lines. Don't
+open with background or acknowledgments. State up front what the document is
+for and what the reader can do after reading it.
+
+- Bad (Japanese example): 「本プロジェクトは日々成長を続けており、多くの貢献者の協力により…」
+- Good (Japanese example): 「kotonoha は技術文書の構成を整えるための Copilot スキルです。README・設計書・PR説明文などを型に沿って書けます。」
+
+## 2. Make headings labels that preview content
+
+Generic labels like "Overview", "Usage", "Notes" tell the reader nothing
+until they read the body. Include *what* is being overviewed or used.
+
+- Bad: `## Overview` `## Usage` `## Notes`
+- Good: `## What kotonoha solves` `## Installing the skill into .github/skills` `## Behavior without sudachipy installed`
+
+## 3. Order steps as executed, and put prerequisites before the steps
+
+Readers execute a document top to bottom. Placing prerequisites
+(dependencies, permissions, prior setup) mid-way or at the end forces
+readers to redo work partway through. Always give prerequisites their own
+section before the steps.
+
+## 4. One action per numbered step
+
+Don't pack multiple actions into one numbered item. "Install A, configure B,
+and run C" should be three steps. Numbered steps let readers track exactly
+where they are.
+
+## 5. Put a concrete example or number right after an abstract term
+
+Words like "fast", "safe", "flexible", "easy to understand" convey nothing
+by themselves. Follow them immediately with a concrete number, condition, or
+code example.
+
+- Bad: "lint.py runs fast."
+- Good: "lint.py processes a 10,000-character document in under 1 second (excluding sudachipy initialization)."
+
+## 6. Keep code examples minimal and runnable; mark omissions explicitly
+
+A code example that doesn't run as copy-pasted costs the reader time before
+they realize it's broken. When omitting something, mark it explicitly (e.g.
+`# ...`) and note that the reader should substitute their own values.
+
+## 7. Disclose known limitations and unsupported cases; don't hide them
+
+"Not yet supported" or "doesn't work under this condition" doesn't lower a
+document's value — it prevents the reader's wasted effort. State it in its
+own section instead of omitting it.
+
+## 8. Keep a last-updated date or target version/branch where staleness is a real risk
+
+A living reference document (README, design doc, API reference, user
+manual) starts going stale the moment it's written. When such a document
+could plausibly be read long after it stops being accurate, state when or
+against what version/branch it was written, so the reader doesn't pay an
+extra verification cost of "is this still accurate?" Skip this rule for
+artifacts whose own metadata already carries that information (a commit
+timestamp, a PR's merge date, a versioned release-notes heading).