eliasoulkadi/shokunin/kami

Note: Full Kami distribution includes ~30+ auxiliary files (CHEATSHEET.md, scripts/, references/, assets/diagrams/*.html). The core SKILL.md works standalone; scripts/build.py is required for PDF generation. Check the Shokunin ecosystem root for these.

kami · 紙

紙 · かみ - the paper your deliverables land on.

Good content deserves good paper. One design language across eight document types: warm parchment canvas, ink-blue accent, serif-led hierarchy, tight editorial rhythm.

Part of Kaku · Waza · Kami - Kaku writes code, Waza drills habits, Kami delivers documents.

Workflow

Step 0 · Load brand profile (if exists)

Check ~/.config/kami/brand.md (preferred) or ~/.kami/brand.md (legacy fallback). If found, read references/brand-profile.md for the full four-layer application spec (placeholder substitution, session defaults, visual customization, habit notes) and its six guardrails. If no profile exists, continue without interruption.

Key rule: explicit prompt > editorial judgment > habit notes > frontmatter defaults > built-in defaults. Profile fills gaps silently; it never overrides the current conversation.

Step 1 · Decide the language

Match the user's language. Chinese -> *.html / slides-weasy.html. English -> *-en.html / slides-weasy-en.html. Japanese -> CJK path (.html / slides-weasy.html) as best-effort, JP Mincho first, visual QA before shipping. Reference docs are shared English specs.

When ambiguous (e.g. a one-word command like "resume"), ask a one-liner rather than guess.

Default to the WeasyPrint HTML path; fall back to PPTX (slides*.py) only when the user explicitly needs an editable deck.

Always use CHEATSHEET.md and references/*.md for design, writing, production, and diagram guidance.

Step 1.5 · Intent extraction (silent checklist)

Before choosing a template, verify these four dimensions are clear. Do not ask unless 2+ are missing and cannot be inferred from context.

Rules:

• If the conversation already answered a dimension, skip it silently.
• If a dimension can be inferred from the document type (e.g. resume purpose is always "get an interview"), skip it.
• If 2+ dimensions are genuinely unclear, ask in a single compact question (max 2 sub-questions).
• Never ask all four as a checklist. This is a background verification, not a form.

Step 2 · Pick the document type

Changelog vs. release notes: The changelog template above is for styled document output. GitHub release notes are a separate deliverable; use /write with Release Note Template Mode.

Slides: default to slides-weasy.html / slides-weasy-en.html (WeasyPrint HTML -> PDF). Use slides.py / slides-en.py only when the user explicitly requires an editable PPTX file.

Deck recipe: read design.md Section 8 before drafting slides.

If unsure, ask a one-liner about the scenario rather than guess.

Diagrams (primitives, not a separate template type)

When the user asks for a diagram inside a long-doc / portfolio / slide (not a standalone document), route to assets/diagrams/ rather than a template:

Read references/diagrams.md before drawing - it has the selection guide, kami token map, and the AI-slop anti-pattern table. Extract the <svg> block from the template and drop it into a <figure> inside long-doc / portfolio.

Before drawing, always ask: would a well-written paragraph teach the reader less than this diagram? If no, don't draw.

Auto-select charts from data. When content contains numerical data, choose the chart type and embed it without waiting for the user to specify. Decision tree (first match wins):

When data fits multiple types, prefer the one that shows variance most clearly. Always embed inside a <figure> with a caption that states the insight, not just the data range.

Step 2.1 · Source and material pass

Run this before distilling or filling content when the document depends on facts or materials outside the user's draft. Skip it only for personal drafts where the user already supplied everything needed.

Source check

Trigger when the document mentions a specific company, product, person, release date, version, funding round, metric, market fact, technical spec, or any current fact likely to change.

• Use primary sources before writing: user-provided material, official site, docs, filings, press release, app store page, or repo release
• Keep a short note of source names and dates for facts that drive the document
• If sources conflict or a fact cannot be checked quickly, ask the user instead of choosing silently
• Avoid current-sounding claims such as "latest", "recent", "new", version numbers, launch dates, or financial figures unless they are checked

Material check

Trigger when the document is about a company, product, project, venue, or personal brand.

Confirm the materials that make the subject recognizable before layout:

If a required item is missing, use a compact gap table and ask once. Do not replace missing material with generic imagery, approximate logo drawings, or invented values.

Materials status block

After the material check, output a structured status block before continuing. This is a one-shot transparency display, not a question:

Materials status:
- Logo: OK assets/client-logo.svg
- Brand colors: OK #1B365D mapped to --brand
- Product screenshot: MISSING (proceeding with kami default placeholder)
- UI screenshot: not required for this doc type

Use OK, MISSING, or not required. If a required item is missing and no user input arrived, ask once with the gap table; otherwise continue silently.

Step 2.5 · Distill raw content (if applicable)

Auto-detect whether to distill. Do not ask the user; judge from the input:

When in doubt, run distill. Distill is cheap; rebuilding a misaligned doc is not.

When the user hands over raw material (meeting notes, brain dump, existing doc in different format, chat transcript, scattered points):

1. Extract: pull out every factual claim, number, date, name, source, material reference, and action item
2. Classify: map each extract to the target template's sections (see references/writing.md for section structure per doc type)
3. Gap-check: list what the template needs but the raw content doesn't have - include missing facts, missing proof, and missing materials
4. Ask once: share the gap table with the user. Do not guess to fill gaps.

Example gap-check: