kotonoha 0.1.0

package/skills/tech-writer/references/doctypes/pr-commit.md

@@ -0,0 +1,82 @@
+# PR description / commit message / issue report type
+
+This doctype directly affects a reviewer's decision speed, so apply it more
+strictly than the other types.
+
+## Commit messages
+
+### Format
+
+```text
+<type>: <summary (imperative mood, ~50 chars)>
+
+<body (optional) - what and why the change was made; the diff already
+shows the "what" implementation details, so don't repeat them>
+
+<footer (optional) - Fixes #123, BREAKING CHANGE: ... etc.>
+```
+
+- Use imperative mood consistently in the summary line (e.g. "Fix", not
+  "Fixed"/"Fixes").
+- The body should explain *why* the change was made, not restate *what*
+  changed — the diff already shows that.
+- One concern per commit. Don't bundle unrelated changes into one commit
+  message.
+
+### Checklist
+
+- [ ] Can the change be inferred from the summary line alone (not just
+      "fix" or "update")?
+- [ ] Does the body explain "why" rather than paraphrase the diff?
+- [ ] Is the related issue number in the footer?
+
+## PR descriptions
+
+### Recommended skeleton
+
+1. **What**: what changed, in 1–3 sentences.
+2. **Why**: why this change is needed (link to the background issue, bug
+   report, or request).
+3. **How**: the main approach. Leave implementation detail to code
+   comments and the diff; state only the design decisions here.
+4. **How to verify**: concrete steps the reviewer can use to reproduce and
+   verify — test commands, or where to find screenshots/GIFs.
+5. **Impact / breaking changes**: state explicitly if this affects other
+   teams' code or API consumers.
+6. **Remaining work / follow-ups** (if applicable): preempt likely review
+   questions about unfinished items.
+
+### Checklist
+
+- [ ] Are What/Why/How separated, so reading only "What" gives the shape
+      of the change?
+- [ ] Are there concrete steps (commands, URLs, repro conditions) the
+      reviewer can use to verify locally?
+- [ ] Are breaking changes, DB migrations, config changes — anything a
+      reviewer could miss and cause an incident — near the top?
+- [ ] Is there a link to the related issue/ticket?
+- [ ] For UI changes, are screenshots actually attached?
+
+## Issue reports (bug reports / feature requests)
+
+### Bug report skeleton
+
+1. **Summary**: the symptom, in one sentence.
+2. **Steps to reproduce**: numbered, with environment info (version, OS,
+   browser, etc.) stated *before* the steps.
+3. **Expected vs. actual result**: contrast them explicitly.
+4. **Impact**: who is affected, and how often.
+
+### Feature request skeleton
+
+1. **Problem to solve**: state the situation causing pain before the
+   feature itself.
+2. **Proposed solution** (optional): if you have one in mind.
+3. **Alternatives considered** (optional).
+
+### Checklist (issues, common)
+
+- [ ] Are the repro steps (or use case) concrete enough to reproduce
+      independent of the reader's environment?
+- [ ] Are "expected" and "actual" explicitly contrasted (bug reports)?
+- [ ] Is environment info stated before the repro steps?

package/skills/tech-writer/references/doctypes/qiita.md

@@ -0,0 +1,68 @@
+# Qiita article type
+
+Like Zenn, the title lives in YAML frontmatter, not an in-body heading.
+Qiita's readership skews toward searching for a specific error message or
+task, so apply rule 3 (order matching how the reader looks for
+information) especially strictly here.
+
+## Target reader
+
+A developer who arrived via search for a specific error, API, or task, and
+is scanning to confirm this article addresses their exact situation.
+
+## Format
+
+Markdown, with Qiita'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>
+tags:
+  - <tag1>
+  - <tag2>
+private: false # true: limited-share draft, false: public
+organization_url_name: null # only if publishing under an Organization
+---
+```
+
+- `title` and `tags` are required; `private` defaults the article to
+  public once posted, so confirm it deliberately rather than leaving the
+  default unconsidered.
+- Qiita CLI also manages `updated_at`/`id`/`slide`/`ignorePublish` fields
+  automatically on publish/update — don't hand-edit those unless you know
+  why.
+
+## Recommended skeleton
+
+1. **Lead paragraph (right after frontmatter, before any heading)**: the
+   specific problem/error/task this article addresses and what the reader
+   will be able to do — this is rule 1's "first three lines" analog, since
+   there's no in-body title to carry it.
+2. **Environment / versions**: state the exact versions (language,
+   framework, OS) the article was verified against, before any steps —
+   Qiita readers frequently hit version-specific breakage.
+3. **Body sections, one concern per `##` heading**: order by how a reader
+   arriving via search would scan (rule 3) — put the fix/answer before
+   background explanation if the article is troubleshooting-oriented.
+4. **Code blocks with both a language tag and, where relevant, a filename**:
+   Qiita supports ` ```js:example.js ` — prefer this over a bare language
+   tag when the file identity matters to the reader.
+5. **References / further reading** (if applicable): official docs or
+   related articles, not a restatement of the body.
+
+## Checklist
+
+- [ ] Are `title` and `tags` present, and is `private` a deliberate choice
+      rather than an unconsidered default?
+- [ ] Does the lead paragraph right after frontmatter state the specific
+      problem/task addressed, since there's no in-body title to do that?
+- [ ] Are the exact versions/environment stated before the steps?
+- [ ] For troubleshooting-oriented articles, does the fix appear before
+      background explanation, matching how a reader arriving via search
+      would scan?
+- [ ] Do code blocks carry a language tag (and a filename where the file
+      identity matters)?

package/skills/tech-writer/references/doctypes/readme.md

@@ -0,0 +1,43 @@
+# README type
+
+The recommended skeleton and checklist for a project README: the document
+most readers see first, and the one that decides whether they keep reading.
+
+## Target reader
+
+Someone visiting this repository for the first time. They want to judge
+"what is this", "do I need it", and "how do I start" within seconds.
+
+## Recommended skeleton
+
+1. **Title + one-sentence description**: right after the project name, say
+   what it does in one sentence.
+2. **What problem it solves (Why)**: problem → approach in 2–4 sentences,
+   before the feature list.
+3. **Key features / what you can do**: a bullet list, one feature per item,
+   starting with a verb.
+4. **Install / setup**: a command sequence that runs as copy-pasted.
+   Prerequisites (versions, OS, permissions) go in a separate section
+   *before* the steps.
+5. **Quickstart, headed with what it does**: the smallest successful
+   experience (a "hello world" equivalent) first, under a heading that
+   previews the concrete task (e.g. "Send your first request"), not the
+   generic label "Usage" (structure constitution rule 2). Move advanced
+   usage to a separate, similarly specific heading.
+6. **Configuration / options** (if applicable): a table (key, default,
+   description).
+7. **Known limitations / what's not supported**: don't omit this.
+8. **Contributing / license**: fine to leave at the end.
+
+## Checklist
+
+- [ ] Does the one-sentence description right after the title convey "what
+      this does"?
+- [ ] Do the install steps run top-to-bottom via copy-paste (no
+      prerequisite hidden mid-steps)?
+- [ ] Is the quickstart section headed with a specific, task-previewing
+      label instead of the generic "Usage", and does it show the smallest
+      successful experience rather than an exhaustive feature list?
+- [ ] Do badges/acknowledgments/license come after the main content, not
+      before it?
+- [ ] Does a known-limitations section exist?

package/skills/tech-writer/references/doctypes/release-notes.md

@@ -0,0 +1,30 @@
+# Release notes / CHANGELOG type
+
+The recommended skeleton and checklist for a per-version changelog entry,
+written for a reader deciding whether and how to upgrade.
+
+## Target reader
+
+An existing user deciding whether to upgrade. Reading time: seconds to a
+few tens of seconds.
+
+## Recommended skeleton
+
+1. **Version + date**: always include both in the heading.
+2. **Breaking changes (topmost, if any)**: what breaks, with a link to the
+   migration steps. This is the one section that must never be omitted or
+   deferred.
+3. **Added / Changed / Fixed / Deprecated / Removed**: categorize per
+   [Keep a Changelog](https://keepachangelog.com/). One change per item,
+   starting with a verb.
+4. **Notes on affected user segments** (if applicable): scope it, e.g.
+   "affects only users of X".
+
+## Checklist
+
+- [ ] Are breaking changes at the top, with a migration path (or link)?
+- [ ] Does each item state "what changed and how" in one sentence (not a
+      raw copy of the commit message)?
+- [ ] Do the categories (Added/Changed/Fixed, etc.) match the actual
+      change?
+- [ ] Are both the version number and the date stated?

package/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/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/skills/tech-writer/references/style-constitution.md

@@ -0,0 +1,89 @@
+# 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 a prose-polishing skill such as natural-japanese).
+
+## 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, Zenn/Qiita article. Apply all 8 rules to those
+doctypes. For Zenn/Qiita specifically, rule 1's "title" lives in YAML
+frontmatter rather than an in-body '#' heading — see their doctype
+reference files for the platform-specific frontmatter fields — but every
+other rule (heading hierarchy starting at '##', 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.
+
+## 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).