kotonoha 0.1.5 → 0.1.6-dev.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Generate Markdown with half-width spaces around `**strong emphasis**`
+  whenever the delimiters would otherwise touch surrounding prose, and flag
+  violations in the structural lint.
+- Add a Qiita article template whose highest-level body sections use `#` and
+  subsections use `##`.
+
 ## [0.1.5] - 2026-09-29
 
 ### Added

package/README.md

@@ -72,8 +72,8 @@ 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, and RFP documents. Every supported doctype includes dedicated structure
-guidance and a review checklist under
+RFI, RFP, and Qiita articles. Every supported doctype includes dedicated
+structure guidance and a review checklist under
 `skills/tech-writer/references/doctypes/`.
 
 ## What presentation-planner does

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kotonoha",
-  "version": "0.1.5",
+  "version": "0.1.6-dev.0",
   "description": "GitHub Copilot CLI skills for technical writing and PPTX presentation planning.",
   "license": "MIT",
   "author": "nahisaho",

package/skills/tech-writer/SKILL.md

@@ -220,8 +220,14 @@ omissions explicitly; disclose known limitations and unsupported cases
 instead of hiding them; and keep a last-updated date or target version
 where staleness is a real risk. For Zenn/Qiita, rule 1's "first three
 lines" maps to the frontmatter `title` plus the lead paragraph right
-after it — see their doctype reference files for why there's no in-body
-'#' title.
+after it. Zenn body sections start at `##`; Qiita body sections start at
+`#` and use `##` for subsections.
+
+For every Markdown doctype, surround `**strong emphasis**` with half-width
+spaces when the delimiters would otherwise touch prose. For example, write
+`これは **強調** になる`, not `これは**強調**にならない`. Spaces are not
+required at line boundaries or next to punctuation, and must not be placed
+inside the `**` delimiters.
 
 For atomic artifacts (commit messages, PR descriptions, issue reports,
 code comments/docstrings, a single entry appended to an existing
@@ -259,9 +265,9 @@ step 2 as the primary check for those.
    (add `--atomic` for a commit message, PR description, issue report,
    code comment/docstring, or a single release-notes entry) to
    mechanically catch heading-level skips, code blocks missing a
-   language tag, leftover placeholders, and suspicious links. Findings
-   are flags, not mandates — deliberate exceptions can stay; note the reason
-   briefly.
+   language tag, leftover placeholders, suspicious links, and strong-emphasis
+   delimiters that directly touch prose. Findings are flags, not mandates —
+   deliberate exceptions can stay; note the reason briefly.
 4. **Reader-goal recheck**: confirm the "what the reader can do after
    reading" outcome from §1 is actually achievable from this document alone.
 

package/skills/tech-writer/assets/templates/qiita.md

@@ -0,0 +1,44 @@
+---
+title: <記事タイトル>
+tags:
+  - <tag1>
+  - <tag2>
+private: false
+organization_url_name: null
+---
+
+<この記事が解決する具体的な課題と、読了後にできるようになることを記載する。>
+
+# 検証した環境
+
+| 項目 | バージョン・値 |
+|---|---|
+| OS | <OSとバージョン> |
+| 言語・ランタイム | <名称とバージョン> |
+| フレームワーク・ライブラリ | <名称とバージョン> |
+
+# <最初に読者へ示す結論・解決方法>
+
+<検索から到達した読者が最短で解決できるよう、結論または実行手順を先に記載する。>
+
+```bash
+<そのまま実行できる最小のコマンド例>
+```
+
+## <手順の前提または補足>
+
+<必要な権限、設定、注意点を記載する。>
+
+# <仕組み・原因・技術的な説明>
+
+<なぜこの方法で解決するのかを、図・コード・具体例を使って説明する。>
+
+# 制約と未対応事項
+
+- <確認できていない環境>
+- <適用できない条件>
+- <既知の制約>
+
+# 参考資料
+
+- [<公式ドキュメント名>](<URL>)

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

@@ -1,9 +1,8 @@
 # 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.
+The article title lives in YAML frontmatter. 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
 
@@ -13,8 +12,8 @@ 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 '##'.
+on top of GFM. The frontmatter `title` is the article title; body sections
+start at `#`, with `##` used for subsections.
 
 ## Recommended frontmatter
 
@@ -36,6 +35,11 @@ organization_url_name: null # only if publishing under an Organization
   automatically on publish/update — don't hand-edit those unless you know
   why.
 
+## Template
+
+Start from `assets/templates/qiita.md`.
+Use `#` for the highest-level body sections and `##` for their subsections.
+
 ## Recommended skeleton
 
 1. **Lead paragraph (right after frontmatter, before any heading)**: the
@@ -45,9 +49,10 @@ organization_url_name: null # only if publishing under an Organization
 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
+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.
+   background explanation if the article is troubleshooting-oriented. Use
+   `##` only for subsections within one concern.
 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.
@@ -60,6 +65,8 @@ organization_url_name: null # only if publishing under an Organization
       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?
+- [ ] Do highest-level body sections use `#`, with `##` reserved for
+      subsections?
 - [ ] 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

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

@@ -38,6 +38,8 @@ outcome. Require it to preserve:
 - 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 half-width spaces between surrounding prose
+  and `**strong emphasis**` delimiters
 - Explicit assumptions, limitations, residual risks, and unresolved items
 
 Heading wording may improve only when its meaning and hierarchy stay intact.

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

@@ -10,11 +10,11 @@ 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, technical proposal, RFI/RFP (including a supplier's RFP
 response), or 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.
+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
@@ -28,6 +28,14 @@ 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 `**重要**: 設定を確認する`. 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

package/skills/tech-writer/scripts/lint.py

@@ -4,12 +4,13 @@
 # dependencies = []
 # ///
 """tech-writer skill: a lint script that mechanically checks a technical
-document's *structure*.
+document's *structure* and Markdown rendering safety.
 
 Where natural-japanese's lint.py detects sentence-level naturalness
-(vocabulary, rhythm), this script only detects structural problems specific
-to technical documents (heading hierarchy, code examples, leftover
-placeholders, suspicious links). The two scripts intentionally don't
+(vocabulary, rhythm), this script detects structural problems specific to
+technical documents plus Markdown syntax patterns that render inconsistently
+(heading hierarchy, code examples, leftover placeholders, suspicious links,
+and bold delimiters touching prose). The two scripts intentionally don't
 overlap in scope.
 
 Findings are flags, not mandates: exit code is always 0 regardless of the
@@ -73,6 +74,7 @@ FENCE_RE = re.compile(r"^(`{3,}|~{3,})(.*)$")
 PLACEHOLDER_RE = re.compile(r"\b(TODO|FIXME|TBD|XXX)\b", re.IGNORECASE)
 MD_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
 INLINE_CODE_RE = re.compile(r"`[^`\n]+`")
+BOLD_RE = re.compile(r"(?<![\\*])\*\*(?!\s)(.+?)(?<!\s)\*\*(?!\*)")
 NON_PARAGRAPH_RE = re.compile(
     r"^(?:[-*+]\s|\d+[.)]\s|>|<!--|\|)|^(?:-{3,}|\*{3,}|_{3,})$"
 )
@@ -243,6 +245,39 @@ def check_links(lines: list, fence_mask: list) -> list:
     return findings
 
 
+def check_bold_spacing(lines: list, fence_mask: list) -> list:
+    """Flag bold delimiters that directly touch surrounding prose.
+
+    Some Markdown renderers fail to recognize strong emphasis when `**`
+    directly adjoins Japanese or other word characters. Punctuation and
+    line boundaries do not need padding.
+    """
+    findings = []
+    for i, line in enumerate(lines):
+        if fence_mask[i]:
+            continue
+        checked = strip_inline_code(line)
+        for match in BOLD_RE.finditer(checked):
+            before = checked[match.start() - 1] if match.start() else ""
+            after = checked[match.end()] if match.end() < len(checked) else ""
+            if (before and (before.isalnum() or before == "_")) or (
+                after and (after.isalnum() or after == "_")
+            ):
+                findings.append(
+                    Finding(
+                        line=i + 1,
+                        category="bold_spacing",
+                        message=(
+                            "Add half-width spaces outside '**...**' when it "
+                            "touches surrounding prose so strong emphasis "
+                            "renders consistently."
+                        ),
+                        snippet=line.strip(),
+                    )
+                )
+    return findings
+
+
 def check_intro_paragraph(lines: list, fence_mask: list) -> list:
     """Check that the document opens with a non-empty H1 title immediately
     followed by a genuine body paragraph.
@@ -315,6 +350,7 @@ def run_lint(path: Path, atomic: bool = False) -> LintResult:
     result.findings.extend(check_heading_hierarchy(lines, fence_mask))
     result.findings.extend(check_placeholders(lines, fence_mask))
     result.findings.extend(check_links(lines, fence_mask))
+    result.findings.extend(check_bold_spacing(lines, fence_mask))
     if not atomic:
         # check_intro_paragraph assumes a living, multi-section document
         # (H1 title + opening paragraph); atomic artifacts like a PR