@gobing-ai/knowledge-kit 0.0.6 → 0.0.8

package/plugins/kk/skills/itc-generating/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: itc-generating
+description: >-
+  Use the itc-generating skill to produce an approved IT technical draft from a
+  topic or Markdown brief, applying the distilled generic IT-writing method and
+  an optional platform playbook — "write an article about X applying the IT
+  writing method", "generate an IT technical draft on X", "create a technical
+  article for WeChat/English platforms". Orchestrates topic (outline + draft),
+  optional storm-research, and optional content-judge without enlarging those skills.
+---
+
+# itc-generating — IT technical draft generation (method + orchestration)
+
+## Purpose
+
+Turn a topic or Markdown brief into an **approved IT technical draft** by applying the distilled
+IT-writing craft and orchestrating the existing `kk` skills — `topic` (outline + draft), optional
+`storm-research` (evidence), optional `content-judge` (technical-accuracy gate). One fat skill with one
+operation, `create`, whose default is the distilled generic-craft method; it delegates outline
+selection and draft review to `topic` and writes the **same topic artifact paths**. This skill owns
+*which* method and *when* to research/judge — it never reimplements topic-core, research, or
+evaluation (D6).
+
+## When to use
+
+- A user asks to write an IT technical article from a topic or brief and wants the distilled
+  IT-writing method applied ("write an IT article about X", "produce a technical draft on X").
+- A user wants a specific platform playbook applied to the draft (`--playbook english` / `wechat`).
+- A user wants the same topic artifact contract but with the writing method and optional
+  research/judging orchestrated around it.
+
+Do **not** use this skill for: a single topic-core step without the method (call `topic` directly);
+research alone (call `storm-research`); evaluating content alone (call `content-judge`); publishing,
+platform adaptation, or image generation (all out of scope); anything requiring a runtime plugin
+(`kk executor run`, `plugin.json`, `GeneratorInput → Content`).
+
+## Invocation contract
+
+`$ARGUMENTS` (or the Skill call args) parse as:
+
+```
+[create] <topic-or-brief> [--dir <target>] [--brief <path>]
+         [--playbook generic|english|wechat]
+         [--research] [--judge]
+         [--outline <a|b|c>] [--revise <feedback>] [--force]
+```
+
+| Token | Meaning | Default |
+| --- | --- | --- |
+| `create` | the only operation; may be omitted | `create` |
+| `<topic-or-brief>` | quoted topic phrase, or `--brief <path>` naming a Markdown brief file | required — empty fails loud |
+| `--dir <target>` | workspace directory | `./<kebab-case(topic)>` (same default as `topic`) |
+| `--playbook <p>` | which reference to load as the writing method | `generic` |
+| `--research` | if the workspace has no evidence, run `storm-research` first | off |
+| `--judge` | after an approved draft, run `content-judge` with the `tech-accuracy` rubric | off |
+| `--outline <a\|b\|c>` | explicit outline selection (passed through to `topic`) | operator selects at the gate |
+| `--revise <feedback>` | revision feedback for the draft review gate (passed through to `topic`) | none (approve path) |
+| `--force` | explicit operator approval to replace an existing artifact (passed through to `topic`) | off — never overwrite without it |
+
+Flags may appear in any order; the first bare positional token is the topic phrase. An unknown
+operation (anything other than `create`) fails loud and lists `create` as the only valid operation.
+
+## References (loaded on demand, R2)
+
+| File | When to load |
+| --- | --- |
+| `references/generic-craft.md` | **always** on every `create` run — the five IT-writing disciplines |
+| `references/platform-english.md` | `--playbook english` — X / Medium / Substack playbook |
+| `references/platform-wechat.md` | `--playbook wechat` — WeChat Official Account playbook |
+| `references/skill-authoring.md` | when reviewing or editing this skill — why it stays lean |
+
+The four STORM studies remain in the works dirs (`~/.config/kk/works/`) as provenance; the skill
+body and references do **not** vendor the full reports (D4).
+
+## Artifact contract (reuses topic, D5)
+
+All paths are relative to the workspace `--dir`. This skill does **not** invent a parallel
+workspace — it delegates to `topic`, which writes exactly these paths:
+
+| Artifact | Path | Written by |
+| --- | --- | --- |
+| Brief | `brief.md` | `topic` `init` |
+| Outline options | `2-outline/outline-option-{a,b,c}.md` | `topic` `outline` |
+| Approved outline | `2-outline/outline-approved.md` | `topic` `outline` (after selection gate) |
+| Draft | `3-draft/draft-article.md` | `topic` `draft` (from approved outline, review gate) |
+
+## create sequence
+
+1. **Input check** (fail loud, R5): empty topic and no `--brief` → stop with recovery. A `--brief`
+   path that does not exist → stop with recovery.
+2. **Target check** (fail loud, R5): if `--dir` exists with a `brief.md` and no `--force` → stop
+   with recovery ("initialization target already exists at `<dir>`; pass `--force` after explicit
+   operator confirmation to replace, or choose a new `--dir`"). Never overwrite without `--force`.
+3. **Load the method** — read `references/generic-craft.md` (always) plus the selected playbook if
+   `--playbook` is not `generic` (R2). If `--research` and the workspace has no reusable evidence,
+   invoke `storm-research` on the topic (XOR: a topic phrase or `--in <file>`); re-run research
+   only when the query or sources must change — reuse existing `docs.json` otherwise.
+4. **Delegate to `topic`** — run `topic create` against `--dir` with the same artifact contract and
+   gates: outline options → explicit selection gate (`--outline <a|b|c>` or interactive) → approved
+   outline → draft → review gate (approve or bounded `--revise`). This skill never reimplements
+   those gates (R1, R3).
+5. **Apply the method while drafting** — using the loaded references, apply the five disciplines
+   (one goal per document, value proposition as scope firewall, explicit prerequisites and POLA,
+   show-don't-tell with diagrams/examples, accessibility) plus the platform playbook's constraints
+   (e.g. WeChat mobile formatting or English-platform framing). The draft is written by `topic`
+   from the approved outline; the method shapes it.
+6. **Optional judge gate** — if `--judge` and `3-draft/draft-article.md` is approved, invoke
+   `content-judge` with the `tech-accuracy` rubric. A non-`PASS` verdict is reported to the operator; it
+   does **not** auto-publish and does not auto-revise past `topic`'s 3-round bound.
+7. **Print** the final artifact paths and stop.
+
+## Fail-loud table (R5)
+
+| Condition | Behavior | Recovery instruction |
+| --- | --- | --- |
+| Empty topic and no `--brief` | Stop; no files created | Provide a topic phrase or `--brief <path>` |
+| `--brief` path does not exist | Stop; no files created | Check the path; supply a real Markdown brief |
+| `--research` with neither topic nor `--in` | Stop; nothing written | Pass exactly one of the topic / `--in <file>` to `storm-research` |
+| Missing prerequisite artifact (e.g. outline before draft) | Stop; nothing written | The recovery comes from `topic` — run the prerequisite step first (see `topic` fail-loud table) |
+| Existing initialization target without `--force` | Stop; no overwrite | Confirm with the operator and pass `--force`, or choose a new `--dir` |
+| Unknown operation | Stop; nothing written | Use `create` (the only operation) or call `topic` / `storm-research` / `content-judge` directly |
+
+Every stop names the exact missing or existing path and the exact next command. Never silently
+skip, never auto-replace, never delete.
+
+## Invariants
+
+- `create` is the **only** operation. Research, illustration, adaptation, and publish operations
+  are **not** added to `topic` — this skill delegates to `storm-research` / `content-judge` (R3).
+- Reuse `topic` artifact paths; never invent a parallel workspace (D5).
+- `topic` / `storm-research` / `content-judge` contracts are unchanged (D6) — this skill only orchestrates.
+- No `plugins/kk/commands/itc*.md`, no `kk` CLI noun/verb, no generator `plugin.json` (R4).
+- Never overwrite an existing artifact without `--force`; bound draft revision at `topic`'s 3
+  rounds.
+- No live publish, no external side effects beyond the delegated research call, no image generation.
+
+## Prompt template (Skill() / agent.run)
+
+```
+Skill(skill="itc-generating",
+  args="<topic-or-brief> [--dir <target>] [--brief <path>] [--playbook generic|english|wechat] [--research] [--judge] [--outline <a|b|c>] [--revise <feedback>] [--force]")
+```
+
+When invoked, follow the `create` sequence above. Load the references the flags select, delegate
+outline selection and draft review to `topic`, and pause for the operator at `topic`'s gates. On
+any stop, output the fail-loud recovery line. The artifact paths under the workspace `--dir` are
+the handoff.

package/plugins/kk/skills/itc-generating/references/generic-craft.md

@@ -0,0 +1,80 @@
+# Generic IT-writing craft — five disciplines
+
+Distilled from the STORM study "How to Write the Best Generic IT Technical Documentation"
+(works dir `how-to-write-the-best-generic-it-technical-docum-0a71c5a7`, provenance only — this
+reference replaces vendoring the full report). Load this reference on every `create` run; apply
+all five disciplines while authoring the draft.
+
+## 1. Structure and scope (the document architect)
+
+- Pick the document types you actually need — and **stop**. There is no universal list; add a
+  document only when no existing one's goal absorbs the content.
+- **One document, one goal**, enforced at review: reread after writing and remove or move
+  anything that does not serve that goal. Write everything first, then cut.
+- **Write the Value Proposition (VP) first**: a one-page list of what the doc will do for its
+  reader (save time, reduce errors, cut training…). It says nothing about format or fonts. Use it
+  as a scope-creep firewall — keep content that supports a VP item, remove the rest.
+- **Plan before writing**: research first (history → latest literature → what existing docs
+  already cover), then a documentation plan (scope, objectives, estimates, workflows, resources).
+  Do not over-invest in placement up front — move a document after it exists.
+- **One goal per section** too: link out to other documents for prerequisites and detail instead
+  of inlining everything.
+
+## 2. Write for the reader (the reader advocate)
+
+- **Profile the readership** enough to structure and customize for them. Do not assume background,
+  environment, context, or that they have read your other docs — link prerequisites instead of
+  inlining them.
+- **Show, don't tell**: lead with diagrams (process flows, C4 views), then explain in prose.
+  Text-based diagrams (Mermaid, PlantUML) stay easy to update. Use at least one concrete example
+  early — a simple example beats an abstract description.
+- **Principle of Least Astonishment (POLA)**: cover the gotchas and non-typical usage up front —
+  undocumented prerequisites, surprising defaults, implicit ordering. Name assumptions, defaults,
+  and prerequisites explicitly.
+- **Long-form craft**: a succinct, jargon-free title; structure against the five Ws + H; write the
+  introduction last, once the content has settled.
+- **Accessibility and inclusive writing** are concrete requirements: follow accessibility
+  guidelines for structure/language; use inclusive example names and bias-free language.
+
+## 3. Make it a team discipline (the engineering manager)
+
+- **Budget for docs time**: measure how long SME review of writer output takes and factor it into
+  each release. Good docs are written once, read hundreds of times.
+- **Close the specialized-skill gap**: technical writing is its own discipline (audience
+  understanding + logical presentation); bring in a technical writer or build review processes
+  that treat writing with the same rigor as code.
+- **Embed docs in the engineering workflow**: docs reviews inside normal PR review, preview builds
+  on each check-in, docs as part of shipping every release — not a post-release afterthought.
+- **Docs are coordination infrastructure** at team scale: they improve knowledge retention and
+  underpin quality, consistency, and compliance.
+- **Build documentation mindshare**: state the problem, start in engineering, gather input
+  broadly, build a taxonomy, make contribution easy, meet regularly.
+
+## 4. Keep it fresh (the maintenance owner)
+
+- **Docs go stale by default**; the countermeasure is procedural — assess doc impact of changes
+  each sprint and allocate update time in the release.
+- **Make updates cheap**: prefer simple human-readable formats (Markdown — diffable in Git) and
+  text-based diagrams so edits stay cheap.
+- **Institutionalize the lifecycle**: plan → write → review → publish, with research up front and
+  maintenance at the end; take occasional content inventories and use reader feedback to fill gaps.
+
+## 5. Tooling and publishing (the pipeline engineer)
+
+- **Match tools to doc types and languages**; when in doubt, defer to Markdown and tooling with
+  simple human-readable formats. A convenient editor matters — you won't write docs you hate
+  editing.
+- **Bake publishing into CI/CD**: build docs from sources and publish on every release; generate
+  docs from code artifacts where possible (OpenAPI is the canonical example).
+- **Plan reuse**: write content once and reuse it (CCMS for cross-product scale); audit for
+  overlap before duplication spreads.
+- **Adopt (or author) style guides**: shared style guides keep output consistent — don't write
+  them from scratch (Write the Docs maintains a living one). During review, get the right experts
+  on the right documents and use preview runs to catch errors before publication.
+
+## Applying this in `create`
+
+While drafting `3-draft/draft-article.md` (after `topic`'s outline gate), apply: one goal per
+document enforced at the draft-review gate; the Value Proposition as a scope firewall; explicit
+prerequisites and POLA; show-don't-tell with diagrams/examples; and accessibility. The `--judge`
+gate then verifies technical accuracy against the rubric.

package/plugins/kk/skills/itc-generating/references/platform-english.md

@@ -0,0 +1,72 @@
+# English-platform playbook (X / Medium / Substack)
+
+Distilled from the STORM study "How to Write and Distribute IT Technical Documents on English
+Platforms" (works dir `how-to-write-it-technical-documents-for-english-a6a76477`, provenance only).
+Load this reference when `--playbook english`; it shapes platform choice, format, and distribution
+for the draft — never reimplements publishing.
+
+## Choose the platform before you write
+
+- The writer's-first-question fallacy: pick a platform *after* deciding what you actually want as
+  a writer. Technical content is expensive to produce; making it for the wrong audience on the
+  wrong surface wastes your scarcest resource.
+- Compare platforms on three axes:
+  - **Growth/discoverability** — Medium: internal distribution, but the algorithm decides reach.
+    X: reach with high volatility. Substack: slow to start, compounds (Notes, recommendations,
+    direct email) into an asset you keep.
+  - **Audience/culture** — X is fast and combative; Medium skews essay readers; Substack readers
+    opt in deliberately (roughly 85% email / 10% app on a typical post).
+  - **Business model** — Medium pays per member read; X monetization is thin for most; Substack is
+    free, you own your subscriber list, paid subs optional (10% cut only when someone pays).
+- For IT writers the email list is the difference between building equity and renting attention.
+  Cross-posting to Medium is a fine low-effort hedge — just understand its mechanics first.
+
+## Launch and grow (Substack)
+
+- Substack is three layers: email newsletter, publication (archive/about/navigation), and
+  social/discovery (Notes, recommendations, search). Most writers only use layer one — that is why
+  they struggle to grow.
+- Setup order: name the publication (clear topic promise or memorable brand — not your personal
+  name unless known); write an attention-grabbing bio (what you write, who it's for, credentials);
+  import any existing subscriber list; publish a first post before promoting.
+- Cadence: a sustainable frequency — one good post per week beats one "perfect" post per month;
+  shipping gets you feedback to iterate. Open each issue with a clear thesis and keep it readable
+  in an email client.
+- **Growth levers combine**: from zero, Notes daily + connecting with writers gets the first
+  50–100 subs; 100–500 layers in guest posts, collaborations, and recommendations (one publication
+  gained ~7,000 subs through recommendations alone).
+- **Notes** is the "new Twitter for writers": short valuable insights, questions, daily presence,
+  genuine engagement (comments, restacks). Not random hot takes or growth-hacking. A 3-2-1 weekly
+  rhythm: three value notes, two engagement posts, one soft promotion.
+- **Own the channel, rent the algorithm**: the email list is the asset that survives platform
+  changes; Notes/X/LinkedIn are top-of-funnel discovery — valuable, volatile, never the foundation.
+
+## Position and voice
+
+- **Author-first** (the newsletter builds an audience for *you*; topics range widely) vs
+  **topic-first** (the publication is the draw; the niche is the promise — "production Kubernetes
+  war stories"). IT content tends to capture niche intent faster topic-first; author-first builds a
+  brand that travels.
+- **Voice is the durable moat**: people want the person behind the publication. When automation
+  repurposes content, preserve conversational voice and framework thinking — never "AI rewrites my
+  stuff," which yields generic output.
+
+## Repurposing (one long-form → many assets)
+
+- One newsletter becomes 5 LinkedIn posts + 10 Substack Notes + 3 X threads via a webhook →
+  extract → generate → deliver pipeline (Make.com + Firecrawl + OpenAI + Google Docs), cutting
+  hours of manual reformatting to ~30 minutes of polish.
+- **Adapt per platform, never copy-paste**: LinkedIn wants declarative hooks + strategic line
+  breaks; Substack Notes wants ~200-character insights with bold + mic-drop endings; X threads
+  need conversational hooks with curiosity gaps between tweets.
+- Dense IT material (architecture tradeoffs, debugging walkthroughs, benchmarks) must be re-cut
+  per surface. Long-form Substack/Medium carries the full technical depth and is the canonical
+  source everything links back to.
+- **The 10–20% human polish pass is mandatory and non-delegable** — for technical material this
+  is where accuracy lives: verify every code snippet, command, flag, and version-specific claim.
+
+## Applying this in `create`
+
+Load this reference when `--playbook english`. It informs the draft's framing (audience, voice,
+platform-native format) and the distribution plan, but the deliverable stays `topic`'s
+`3-draft/draft-article.md` — this playbook never publishes and never writes a parallel artifact.

package/plugins/kk/skills/itc-generating/references/platform-wechat.md

@@ -0,0 +1,60 @@
+# WeChat Official Account playbook (specific-platform study)
+
+Distilled from the STORM study "How to Write and Publish Technical Documents on WeChat Official
+Accounts" (works dir `how-to-write-it-technical-documents-for-specific-d158f7c2`, provenance only).
+Load this reference when `--playbook wechat`; it shapes the draft for WeChat's reading context and
+compliance constraints — never reimplements registration, publishing, or the API.
+
+## Why WeChat
+
+- For Chinese academics, engineers, and technical decision-makers, WeChat Official Accounts
+  (微信公众号) are the primary delivery channel — researchers check it almost every waking hour.
+- Authority bar: an expert should be able to name at least five public accounts on the topic they
+  follow. If your account would not make that list, you are not reaching the expert audience.
+
+## Account type and constraints (the drafting context)
+
+- **Subscription account (订阅号)**: up to 1 push/day, but folded into a "Subscriptions" folder —
+  best for high-cadence technical publishing. **Service account (服务号)**: 4 messages/month but
+  appears in the main chat list with push — best for low-cadence, high-importance announcements.
+- **Enterprise accounts (企业号)** are for internal newsletters (mutual approval, no public reach).
+- **Hard limits that shape content**: each message carries up to 8 articles; **published articles
+  cannot be deleted** — only modified with a correction notice. Errors are permanent, so
+  review-before-publish is mandatory.
+- Registration is a Chinese-identity-bound process (QR-scan binding, Chinese ID/phone for admins,
+  ICP / Mini Program filings for hosted infrastructure). Foreign entities must work through a
+  Chinese partner. API access needs AppID/AppSecret (QR-verified) and an IP whitelist.
+
+## Authoring for the WeChat reader
+
+- **Markdown-first pipeline**: WeChat's rich-text editor cannot interpret Markdown. Write in
+  Markdown, convert to WeChat-compatible rich text (MD2WeChat / `lyricat/wechat-format`, or the
+  Obsidian `wechat-public-platform` plugin for one-command draft upload), then paste/upload.
+  Converters turn external links into footnotes (external links are not allowed in articles).
+- **Format for mobile consumption** (articles are read on phones — commuting, mid-meeting):
+  short paragraphs, images/GIFs/audio/video (text-only underperforms), text-light images, abstract
+  (摘要) under 120 characters, 900×500px cover, Simplified Chinese, short self-explanatory titles
+  (truncated after ~26 Chinese characters), h2–h4 headings (leave h1 for larger embedding), 15px
+  body text, PingFang on iOS.
+- **Language**: Chinese-language articles outperform English even for Chinese academics who read
+  English; some international accounts publish multilingual content.
+- **What engages**: novelty (new findings/new resources), originality and authenticity, and
+  structural rigor — this audience is trained to be critical of a WeChat post.
+
+## Editorial standards for authority
+
+- **Bilingual/translated material**: the CAICT model — long-form Chinese analyses of international
+  technical reports, crediting Chinese-institution contributors — is the reference pattern.
+- **Worth a "top five" slot**: recurring high-signal formats (standards announcements, seminar
+  notices, joint research, translated analyses) plus originality, authenticity, and rigor.
+- **Review-before-publish checklist** (forced by the no-deletion rule): preview to your own WeChat
+  first; verify title length, abstract, cover, and footnote-converted links; confirm originality
+  declaration, tags, and comment settings manually in the draft box; route the broadcast through
+  the admin QR-code verification step.
+
+## Applying this in `create`
+
+Load this reference when `--playbook wechat`. It informs the draft's structure (mobile-first
+formatting, Chinese-language expectations, title/abstract limits, review rigor) but the deliverable
+stays `topic`'s `3-draft/draft-article.md` — this playbook never registers an account, never
+publishes, and never touches the WeChat API.

package/plugins/kk/skills/itc-generating/references/skill-authoring.md

@@ -0,0 +1,62 @@
+# Skill-authoring self-discipline (why this skill stays lean)
+
+Distilled from the STORM study "How to Write the Best Technical Documentation with Agent Skills"
+(works dir `how-to-write-the-best-technical-document-with-ex-2c52b35c`, provenance only). This
+reference is the meta-discipline for *this skill*: it exists so `itc-generating` stays a thin
+method+orchestration layer instead of re-vendoring craft or reimplementing sibling skills.
+
+## The SKILL.md contract (hard limits)
+
+- **Frontmatter**: `name` ≤64 chars, lowercase letters/numbers/hyphens only, no XML tags or
+  reserved words, and must exactly match the parent directory name. `description` is non-empty,
+  ≤1,024 chars, no XML tags.
+- **Body budget**: keep SKILL.md under ~500 lines / ~5,000 tokens — just the core instructions the
+  agent needs every run; split the rest into `references/`.
+- **Context economics**: only `name` + `description` are pre-loaded; the rest enters context only
+  when needed. The description is the *only* routing signal — write it as a third-person capability
+  statement with explicit negative triggers so near-miss tasks are excluded.
+- **Folder grammar**: SKILL.md + `references/` + `scripts/` + `assets/`, kept **exactly one level
+  deep** (`references/schema.md`, not `references/db/v1/schema.md`). Avoid nested reference chains —
+  when references point at references, the agent previews instead of reading fully.
+
+## Progressive disclosure (the load-on-demand rule)
+
+- Keep the always-loaded core minimal; push detail into `references/` with **just-in-time
+  pointers**: "Read `references/api-errors.md` if the API returns a non-200" beats "see
+  references/ for details".
+- Three patterns: high-level guide + references; domain-specific organization; conditional details
+  (branch to a section only when a condition holds).
+- Prefer **deterministic scripts** for fragile/repetitive operations (link checks, format
+  validation) — not for judgment-heavy authoring. Design their failure modes deliberately.
+
+## Instruction design
+
+- **Degree of freedom**: prescriptive exact-sequence instructions for fragile operations; goal-plus-
+  philosophy for judgment-heavy work (authoring). Vague skills fail — "handle errors appropriately"
+  carries no information.
+- **Defaults, not menus**: pick one default and a one-line escape hatch, rather than listing
+  options and hoping the agent chooses well.
+- **Add what the agent lacks; omit what it knows**: the filter is "would the agent get this wrong
+  without this instruction?" If no, cut it.
+- Highest-value blocks: gotchas sections (environment facts that defy assumptions), output-format
+  templates, checklists and self-check loops.
+
+## Evaluation and review (how to keep improving the skill)
+
+- Four validation passes: discovery (description in isolation — does it route correctly?),
+  logic (deterministic steps, no hallucinated gaps), adversarial edge-case QA ("try to break this
+  skill"), architecture refinement (enforce progressive disclosure).
+- **Execute-then-refine** beats endless pre-polish: run the skill on real tasks and iterate;
+  read execution traces, not just outputs (instructions retried many times, instructions followed
+  that don't apply, too many options without a default).
+- Add a **self-reflection step**: after a run, examine the friction log and improve the skill so
+  the next run does not struggle the same way.
+
+## How this skill applies it
+
+`itc-generating` is one-level-deep by construction: SKILL.md points at the four `references/*.md`
+files below it and loads them on demand (generic-craft always; playbook only when `--playbook` is
+not `generic`). It reuses `topic`'s artifact contract rather than inventing a parallel workspace
+(D5), delegates research/judging to `storm-research`/`content-judge` rather than reimplementing them (D6),
+and stays under the body budget because the four STORM reports live in the works dirs as
+provenance — never vendored here (D4).

package/plugins/kk/skills/storm-research/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: storm-research
+description: >-
+  Use the storm-research skill to run daily STORM research — turn a research topic
+  sentence or a markdown source file into a grounded STORM Content report with a content.md
+  sidecar ("research X", "produce a research report on X", "run today's STORM research",
+  "turn this brief into a researched report"). The machine is the 0059 workflow
+  (prepare → ingest → generate → render) over the 0056 works layout. Research is separate from
+  authoring: topic owns init→outline→draft and this skill never merges into topic.
+version: 0.1.0
+---
+
+# storm-research — STORM daily research (topic sentence XOR markdown file → content.md)
+
+## Purpose
+
+Turn one research topic (a sentence) or one markdown source file into a **grounded STORM
+`Content` report** plus a `content.md` sidecar by composing the `web-search` ingestion plugin,
+the `content-gen` generator, and the `render-md` helper. The machine is the 0059 workflow
+(`prepare → ingest → generate → render → done|failed`); this skill owns the **craft** — framing
+the query, deciding when to re-run ingest, and verifying the report against the evidence.
+
+Research is **not** authoring. `topic` owns `init → outline → draft` from an approved
+outline; this skill owns evidence gathering. **Do not merge this into `topic`.**
+
+## When to use / not to use
+
+Use when:
+
+- A user asks to research a topic: "research X", "produce a research report on X", "run today's
+  STORM research", "what does the evidence say about X".
+- A user supplies a markdown source (brief, notes, outline) that should ground the report —
+  pass it with `--in <file>`.
+
+Do **not** use for:
+
+- Authoring an article from a topic with no research need — that is `topic`.
+- Quality gating / judging generated content — that is `content-judge`.
+- Publishing, platform adaptation, or illustration — out of C4 scope.
+- Anything requiring a raw `kk executor run` chain when the workflow already composes it.
+
+## Invocation contract
+
+Same arguments as `/workflow-run` (the thin command delegates here for craft):
+
+```
+[workflow-name] <topic | --in <file>> [--fixture] [--force]
+```
+
+| Token | Meaning | Default |
+| --- | --- | --- |
+| `workflow-name` | installed workflow YAML name; must match `^[a-z0-9][a-z0-9-]*$` and not be `--in` | `kk-storm-research` |
+| `<topic>` | a **specific research question** (better-report a — prefer a question over a noun phrase) | required unless `--in` |
+| `--in <file>` | markdown file mode (XOR with `<topic>`) | — |
+| `--fixture` | force `fixture: "true"` (offline stub ingest) | config default (`false` for real runs) |
+| `--force` | overwrite an existing dest workflow YAML | off |
+
+**XOR rule:** exactly one of `<topic>` / `--in <file>` must be set. Both set or both empty →
+fail loud, no writes. `--in` and a bare topic token are mutually exclusive.
+
+The operator invocation in practice is `/workflow-run <topic>` or `/workflow-run --in <file>`; the
+skill is also callable directly as `Skill(skill="storm-research", args="<topic|--in file> ...")`.
+
+## How to run
+
+1. **Frame the query** (better-report a): prefer a specific question over a noun phrase.
+   "What are the known failure modes of vector databases at 1B rows?" beats "vector databases".
+   A question constrains the search and the report; a noun phrase invites scope creep.
+2. **Choose input**: topic sentence, or a markdown file via `--in` (XOR). File mode derives the
+   query from the first ATX H1 (`/^#\s+(.+)$/m`), else the basename without extension.
+3. **`work_dir` is the resolved topic directory** `$works_dir/<topic-id>`, computed by the
+   invoker (the command or the operator) via the 0056 `topicId()` algorithm — never by the
+   workflow. `prepare` only `mkdir` + materializes files into `${vars.work_dir}`.
+4. **Pick fixture vs live** (see below). Default is live (`fixture: "false"`); pass
+   `fixture: "true"` for offline/dry-run/CI.
+5. **Run** the workflow and collect the outputs: `content.md` (report sidecar), `content.json`
+   (machine contract), `docs.json` (evidence). Read the report against the evidence before
+   presenting it (better-report d).
+
+## topicId algorithm (0056, frozen)
+
+`topicId(raw: string)` — computed by the **invoker**, never by the workflow YAML:
+
+1. `normalized` = trim, collapse whitespace, lowercase.
+2. `slug` = replace `[^a-z0-9]+` with `-`, squeeze dashes, trim dashes, slice to **48 chars**,
+   trim dashes again. If empty → `topic`.
+3. `hash` = `sha256(normalized).digest('hex').slice(0, 8)`.
+4. Return `slug + '-' + hash`.
+
+- Sentence mode: `raw` = the topic string. File mode: `raw` = first ATX H1 else basename
+  without extension.
+- Same `raw` → same id → same workspace. **Last write wins**; do not fail on an existing
+  works dir (re-running a topic is legal — no `--force` needed).
+- If `raw` derives empty (no H1 and an empty basename, e.g. a file named `.md`) → fail loud.
+
+## Works layout (0056, frozen; ADR-013 adds `references/`)
+
+Per-topic workspace at `$works_dir/<topic-id>/`:
+
+| File | Written by | Contents |
+| --- | --- | --- |
+| `topic.json` | prepare | ingest `--in` (`topic`, `maxResults`, `fixture`) |
+| `input.md` | prepare (file mode only) | verbatim copy of the operator file |
+| `local-doc.json` | prepare (file mode only) | one-element `Doc[]` (id = `sha256('file://'+absPath).hex.slice(0,16)`, rank `-1`, position `0`) |
+| `docs.json` | ingest | `web-search` output `Doc[]` |
+| `content.json` | generate | STORM `Content` (machine contract) |
+| `content.md` | render | markdown sidecar report |
+| `references/<doc-id>.md` | ingest (live path only) | normalized full content per source (`/v2/scrape` → markitdown); file name = Doc id; audit trail and the citation-resolution target for the report tail (ADR-013) |
+
+Contrast: `topic`'s authoring workspace is `./<kebab-case(topic)>` with `brief.md` /
+`2-outline/` / `3-draft/` and explicitly excludes research. C4 works live under `$works_dir`,
+outside any repo.
+
+## Live vs fixture
+
+| Mode | `fixture` | Behavior | Requires |
+| --- | --- | --- | --- |
+| Live | `"false"` (default) | `web-search` calls the Firecrawl search API (`POST https://api.firecrawl.dev/v2/search`, `scrapeOptions.formats: ["markdown"]`), maps `data.web[]` to `Doc[]` | `FIRECRAWL_API_KEY` env var; unset → the ingest exits 1 ("FIRECRAWL_API_KEY is unset") |
+| Fixture | `"true"` | `web-search` emits canned `Doc[]` (stable `sha256(sourceUri)` ids); no network, no key | none — offline/dry-run/CI |
+
+- `FIRECRAWL_API_KEY` is **env-only** — never a config key, never a workflow var, never in the
+  report.
+- Real daily research defaults to live. **`fixture: true` is not research** (better-report b) —
+  the canned docs are for machine checks, not for evidence a reader should trust.
+
+## Fail-loud table (0056 rows the agent must execute)
+
+| Condition | Behavior | Recovery |
+| --- | --- | --- |
+| Both `<topic>` and `--in` set, or neither | exit 1, stderr states the XOR rule; no writes | pass exactly one of `topic` / `--in` |
+| `--in` file unreadable (missing / I/O) | exit 1, stderr names the path | fix the path / permissions |
+| Derived query / topic-id empty (no H1 and empty basename) | exit 1, stderr shows the derived value | add an H1 or give the file a real name |
+| Dest `$workflows_dir/<name>.yaml` exists with different bytes | warning, **no overwrite**; run proceeds with the user's copy | re-run with `--force` to replace from the install source |
+| Workflow YAML cannot be resolved from any install source | exit 1, stderr lists the roots searched (`KK_WORKFLOWS_SOURCE`, `plugins/kk/workflows`) | reinstall the package / set `KK_WORKFLOWS_SOURCE` |
+| `KK_CONFIG` set but unreadable, or config unparseable / invalid types | exit 1, stderr names the key + expected vs actual type | fix the file, or delete it (recreated with defaults next run) |
+| Missing config at `KK_CONFIG` | **not a failure** — create-on-first-run with compiled defaults; an existing file is never overwritten | — |
+| `markitdown` missing from `PATH` (live mode) | ingest exit 1, stderr `web-search failed: markitdown is not on PATH`; probed before any network call, so no `docs.json` write | install markitdown / put it on `PATH`, re-run ingest |
+
+Every failure names the exact path and the exact next command. Never silently skip, never
+auto-replace, never hash topic-id in the YAML.
+
+## Better-report practices (R1)
+
+1. **(a) Prefer a specific question over a noun phrase.** A question ("How does X behave under
+   Y?") pins the search and the report's thesis; a noun ("X") leaves scope open.
+2. **(b) Do not treat `fixture: true` as research.** Fixture output is canned — fine for
+   pipeline checks, never a source of claims to present to a reader.
+3. **(c) Re-run ingest only when the query or sources must change.** If the question is
+   unchanged and the sources are the same, **reuse `docs.json`** — do not re-fetch. Only a new
+   query, new sources, or stale evidence justifies a fresh ingest.
+4. **(d) Read `content.md` citations against `docs.json` ids.** Every citation in the report
+   must resolve to a Doc id present in `docs.json`; verify the claim against that Doc's body
+   before trusting it. A citation to a missing id is a defect — fix the report, not the id list.
+5. **Cap `maxResults` before widening.** Start at the default (`8`); only widen when the first
+   pass demonstrably misses coverage. More results is not better grounding — it is more noise.
+6. **Prefer primary sources in the markdown input file.** When a source file is supplied via
+   `--in`, favor the primary material in it (first-party specs, owned notes, authoritative
+   extracts) as the spine of the report; web results fill gaps, not the reverse.
+7. **Digest, don't index.** References are evidence, not the deliverable: the report synthesizes
+   findings across the supplied documents, compares them, and states conclusions — it never
+   lists sources one per line. The render drops the `## Outline` replay (ADR-013 D7); the
+   references tail plus `references/<doc-id>.md` files are the audit trail behind each cite id.
+
+## Invariants
+
+- The invoker computes `topicId` and passes `work_dir` resolved; the workflow never hashes.
+- XOR input always — exactly one of `topic` / `input_file`.
+- Never promise a judge gate or query expansion in this skill (C4 scope: neither exists).
+- No new `kk` first-layer noun (ADR-011) — this skill runs through the workflow, not through a
+  `kk` CLI verb.
+- `FIRECRAWL_API_KEY` stays env-only.
+- Works layout file names are frozen (0056) — do not rename or add sidecars in this skill.
+  ADR-013 exception: the ingest live path writes `references/<doc-id>.md` per cached source.

package/plugins/kk/skills/{kk-topic → topic}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: kk-topic
+name: topic
 description: >-
-  Use the kk-topic skill to author technical content from a topic or Markdown
+  Use the topic skill to author technical content from a topic or Markdown
   brief — "create an article from this topic", "turn this brief into a draft",
   "generate outline options", "initialize a topic workspace", "resume my draft".
   Runs the topic-core authoring loop (init → outline → draft) through four
@@ -9,7 +9,7 @@ description: >-
   cohesive topic-authoring core, harvested from the WT 7-stage wrappers.
 ---
 
-# kk-topic — topic-core authoring (create | init | outline | draft)
+# topic — topic-core authoring (create | init | outline | draft)
 
 ## Purpose
 
@@ -159,7 +159,7 @@ silently skip, never auto-replace, never delete.
 ## Prompt template (Skill() / agent.run)
 
 ```
-Skill(skill="kk-topic",
+Skill(skill="topic",
   args="<operation> <topic-or-brief> [--dir <target>] [--outline <a|b|c>] [--revise <feedback>] [--force]")
 ```