acostanzo/doc

Inkwell:doc

Write or update a doc under the repo's docs/ tree. The skill is the writer's primary scaffolding surface: it picks a Diátaxis template, substitutes the topic into the headline placeholders, seeds a ## Related block from the link suggester, and refreshes the FTS5 index so the new doc is immediately searchable via /inkwell:search.

Inputs

• <topic> — required. Free-form topic title. Used both to derive the filename slug and to substitute the template's headline placeholders (<Topic>, <Goal>, <Surface>, <What you'll learn>).
• --template <name> — optional. One of concept, how-to, reference, tutorial. Overrides the auto-pick.
• --from-code <path> — optional. Source file to draft a reference-shaped doc from. Forces --template reference if no explicit template was given.

Behaviour

1. Resolve target path

Call the resolver with the raw topic:

bash "${CLAUDE_PLUGIN_ROOT}/bin/inkwell-doc-resolve.sh" \
    "<topic>" "<REPO_ROOT>"

The resolver emits one of three outputs on a single line:

• match <relative-path> — exactly one existing doc matches by filename slug or by frontmatter title: (case-insensitive). Take the update path (§2a) against this file.
• ambiguous <path1> <path2> ... — two or more docs share a title: matching <topic> and no slug match exists. Surface the candidates to the user and stop; do not scaffold a third copy. The author resolves the ambiguity (e.g. by re-running with a more specific topic, or by editing one of the candidates manually first).
• none — no existing doc to update. Take the scaffold path (§2b).

The resolver checks slug first (the strongest signal — it's the write-target the scaffold path would otherwise create) and falls back to a title: scan so a topic like Authentication finds an existing docs/concepts/auth.md rather than scaffolding a duplicate at docs/authentication.md.

2a. Existing doc → update path

If the resolver returned match <path>:

1. Read the file.
2. Edit the updated: line in the frontmatter to today's date (UTC, YYYY-MM-DD). Today's date is available as the {{ today }} substitution in the conversation context, or compute via Bash: date -u +%Y-%m-%d.
3. Write nothing else. The body and other frontmatter are the author's, not yours — /inkwell:doc updates the updated: stamp, not the prose. Semantic rewrites belong to /inkwell:tidy --apply-semantic (T4).
4. Skip to §3 (index refresh).

2b. New doc → scaffold path

If the resolver returned none:

1. Pick the template. If --template <name> was supplied, use it. Otherwise auto-pick from the topic shape:

   • Starts with "How to " (case-insensitive) → how-to
   • Starts with "What is " → concept
   • Starts with "Get started" / "Build your first" / "Tutorial" → tutorial
   • Contains a ( and ) (function signature shape) or contains a path separator (/ between non-space tokens, suggesting a file) → reference
   • Otherwise → concept (conservative default).

2. --from-code <path> overrides the auto-pick to reference (a doc generated from source code is reference-shaped by definition, unless the author explicitly asks for another template).

3. Read the chosen template at ${CLAUDE_PLUGIN_ROOT}/templates/<template>.md.

4. Substitute placeholders. In the template body, replace:

   • <Topic> → the user's <topic> (concept/reference)
   • <Goal> → the user's <topic> (how-to)
   • <Surface> → the user's <topic> (reference)
   • <What you'll learn> → the user's <topic> (tutorial)
   • The updated: frontmatter value → today's date.

5. --from-code enrichment. If --from-code <path> is given:

   • Read the source file.
   • For known languages, seed the ## Parameters table with the exported function signatures (Python def, JS/TS export function, Go func). The reference template's table is four columns — Name | Type | Default | Description — so each row must be | name | — | — | — | <one-line meaning> | (5 pipes, 4 cells). Populate type/default if you can extract them from source; otherwise leave the em-dash placeholders. Leave the meaning blank if you can't extract a docstring — the author fills it in.
   • Add a one-line ## Description paragraph naming the source path so the doc is self-locating.

6. Write the new file at <REPO_ROOT>/docs/<template-dir>/<slug>.md with the substituted body and an empty ## Related block (the heading followed by the placeholder). <template-dir> is the conventional Diátaxis directory name, mapped from the chosen template:

   | Template | Directory | |---|---| | concept | concepts/ | | how-to | howtos/ | | reference | reference/ | | tutorial | tutorials/ |

   The template files are named singular (concept.md, how-to.md, reference.md, tutorial.md); the on-disk neighbourhoods are plural (concepts/, howtos/, tutorials/) where natural and un-hyphenated (howtos). The mapping above is the source of truth — keep both halves in sync.

   Run mkdir -p <REPO_ROOT>/docs/<template-dir> before the write so the destination directory exists. The file must exist on disk before the suggester runs because the suggester reads the target's frontmatter tags: to score peers — it refuses a non-existent target.

   The resolver (inkwell-doc-resolve.sh) scans docs/**/*.md recursively, so existing docs at any depth continue to be found on the update path; only the scaffold path picks the subdirectory.

7. Suggest ## Related. Call the suggester against the now-existent path:

   bash "${CLAUDE_PLUGIN_ROOT}/bin/inkwell-suggest-links.sh" \
       "docs/<template-dir>/<slug>.md" "<REPO_ROOT>"
   

   The script returns either path score=... rationale: ... lines on stdout or no automatic suggestion on stderr.

8. Edit the ## Related block. Templates ship with the <!-- inkwell:related — populate when the doc earns siblings --> placeholder. If the suggester emitted candidates, replace that comment with one bullet per candidate (- [path](path)). If the suggester emitted "no automatic suggestion", leave the comment in place — inkwell-tidy.sh treats it as writer-acknowledged-empty and won't fire missing-related against fresh scaffolds.

3. Refresh the FTS5 index

Always run, regardless of update or create path:

bash "${CLAUDE_PLUGIN_ROOT}/bin/inkwell-index.sh" "<REPO_ROOT>"

The indexer is mtime-cached and idempotent — touching only the file just written. The on-write index refresh is what makes /inkwell:search reflect the new doc immediately, no manual reindex.

Voice

The doc you write must match the inkwell voice (see plugin README § "Documentation voice"):

• LLM-first, then engineers, then product team.
• Structured and scannable — headings are semantic, sections are one idea.
• Concrete — file paths spelled out, function names in code spans.
• Self-contained — a reader (human or LLM) shouldn't need adjacent files to follow this one.
• Plain-spoken — engineering documentation is not marketing copy.

The templates ship with <!-- comment --> guidance under each section. Delete those guidance comments before saving — they're authoring scaffolding, not output content.

What this skill does not do

• Does not author the prose. The user is the author; the skill scaffolds, substitutes, and seeds.
• Does not enforce template compliance. Sections are soft scaffolding per the plan's "Document model" section. Compliance scoring is T5's score-template-compliance.sh, not this skill's concern.
• Does not corroborate code. That's /inkwell:query (T3) at inference time, per ADR-007.
• Does not modify files outside docs/<slug>.md and the gitignored index file. ADR-006 §2 holds: no silent mutation of consumer artefacts.