zby/commonplace/cp-skill-write

EXECUTE NOW

Target: $ARGUMENTS

Intent. Produce a document that is aligned with this KB's doctrine: the standing rules in the root AGENTS.md, the target collection's COLLECTION.md, the document's type spec, and the Universal Mechanics below. Together they fix what the document may contribute, its quality bar, structure, vocabulary, and links. When done, the document is saved at its resolved path, meets those rules, has its source-dependent claims grounded, and passes commonplace-validate. This skill authors only: link discovery beyond a duplicate guard belongs to cp-skill-connect, source records to cp-skill-ingest, and verification to a human. The step order binds where it protects the target: the source guard (Step 7) finishes before the first write (Step 8). Wording, and structure within the type contract, are the writer's choice.

All documents in the KB live in a collection: a directory under kb/ with a local COLLECTION.md, such as kb/theory/, kb/reference/, or kb/instructions/. Each collection that accepts writes has a COLLECTION.md with its purpose, intended contribution, quality goal, and linking conventions.

Documents with frontmatter carry a type: that names a type-spec doc. The value is the spec's path under a KB root, with .md. A global type, defined in the Commonplace library's types/ directory, is named by its path under the library root, for example type: types/note.md. A collection-local type is named by its path under the KB root, starting with its collection, for example type: reference/types/adr.md. Bare names and values starting with ./, ../, or kb/ are invalid. Files with no frontmatter are implicit text. The library's global types are at ../../types/, resolved from this skill's real location.

Step 1 - Parse Arguments

Edit mode: first argument is a path to an existing .md file. Read it, infer collection from the path, and read its type: path from frontmatter. If it has frontmatter but no type:, stop and fix that structural problem before editing. If it has no frontmatter, treat it as implicit text. Open the type-spec doc named by type: before making structural edits. If it declares brief:, read the sibling brief it names; Step 4 uses it. A target whose own type is types/write-brief.md is a brief: edit it like any document, and do not look for a brief of a brief.

New-write mode: everything else. Extract collection, type, and topic from the arguments. Default an unspecified type to types/note.md. Use the collection supplied by the caller or selected by the project's authored routing for this contribution; in this KB, theoretical notes go to theory, while scaffold projects commonly use notes. If routing does not select one collection, ask. If the requested type is an instruction and no collection is explicit, use collection instructions.

For new writes, resolve the target collection to a directory under kb/ with a local COLLECTION.md; shorthand names such as theory mean kb/theory/, while notes means kb/notes/ when that collection exists. Do not treat either as an alias for the other. Resolve the type independently of the collection contract:

• If the user or calling workflow supplied a type value, open the file it names and verify that its own frontmatter identifies it as a type-spec doc. A global value types/<name>.md names ../../types/<name>.md from this skill's real location; a local value names a file under the project's kb/.
• If the user supplied a shorthand type name, look for it among the library's global types (../../types/<name>.md) and in every collection types/ directory below kb/. Inspect each candidate's own opening frontmatter and require exactly one type-spec doc whose name: equals the shorthand. Write the match as its path under its root: types/<name>.md for a global type, <collection>/types/<name>.md for a local one. If none or several match, stop and report the matches; do not guess or apply collection-specific precedence.
• If no type was supplied, use types/note.md.

This lookup identifies the contract; it does not authorize the type for the target collection. Do not add collection-specific eligibility logic or a kb/work/ branch. commonplace-validate owns that decision. An explicit request for text means frontmatter-free Markdown, not a type: pointer.

Step 2 - Load Collection Conventions

Read the target collection's COLLECTION.md for the collection's writing conventions, including outbound-linking rules. Find the outbound-linking section (heading varies — look for the one that names destinations and labels) and treat it as authoritative. It tells you which local collections this source may link to, whether the reserved external destination is authorized, which destinations are excluded, which labels are authorised for which source->destination pairs, and the reader-need each label serves. The destination wildcard any includes external. Internal format varies (per-destination blocks, a single labels table with a destinations column, prose) — read it for content, not shape. There is no separate linking doc to consult.

Hard fail if the target collection has no COLLECTION.md. Every collection that accepts writes must have a COLLECTION.md; its purpose, intended contribution, quality goal, and linking rules are what distinguish collections. Do not proceed with default conventions.

Step 3 - Load The Type Spec

Read the selected type-spec doc. Its frontmatter must include type: types/type-spec.md, name, description, and schema. Its body supplies the document shape and may include a template block. Follow that body as the structural authoring contract.

Do not fall back from a missing type path to note.

For text, write raw markdown with no frontmatter only when the user explicitly wants unstructured capture. Otherwise use note.

Step 4 - Resolve The Intended Contribution

Before drafting, identify from the user's request and the target document in edit mode:

• the intended audience, using the collection default when the task does not narrow it;
• the governing question, target claim, or practical purpose (for a document that directs someone to act, this becomes the intent that opens it; see "Directive text" under Universal Mechanics);
• what the reader should understand, infer, or do because this document exists; and
• any scope or angle needed to distinguish it from materially different documents on the same topic.

The repository and collection contracts constrain the acceptable contribution class, quality bar, and often the default audience. They do not by themselves select a document-specific claim or purpose. Resolve that choice from the task, the incumbent document, and any retained intent supplied for this write. Treat a context block as retained intent only when it identifies its source, subject, scope, and whether its role is authoritative or advisory. Current user direction prevails. If retained intent conflicts with the incumbent or another applicable input and no explicit precedence resolves the conflict, ask the user rather than silently amending the commission.

Write briefs. When the target declares a brief: (write-brief type), the brief is this document's retained intent: its source is the brief file, its subject is the target, and it is authoritative for intent until a user amends it. Keep what it says to keep and exclude what it says to exclude. When the current request conflicts with a brief item, the request prevails: make the change, name the brief item it amends in your final report, and update the brief in the same write so it states the new commission. Ask instead only when the request does not settle how the brief should change.

When you commission a document — a new write, or an edit that changes what the document is for — and the request fixes boundaries a later writer could not infer from the finished document (passages another artifact relies on, deliberate exclusions, a claim that must not be expanded, decisions reserved for the user), write a brief for it: the sibling <stem>.brief.md under the write-brief type, and brief: <stem>.brief.md in the target's frontmatter. Write the brief from the request, not from your draft. Skip it when the commission is only a claim and its reader update; the title and opening carry that.

Remembered intent may complete a bare request, but it is not meaning contained in that request, a choice licensed by model priors, or evidence that warrants factual claims. Do not add an ad hoc history search to this skill; older interaction history counts only when a memory mechanism supplies it through the retained-intent input.

When those inputs already determine the choices, proceed without a formal brief. If several materially different contributions still fit, treat that as a specification gap rather than something a stronger model should guess: ask one focused question, or use an exploratory workshop when determining the contribution is itself the work. When the contribution is determined but its claims still need substantial grounding or synthesis, stop and explain why the ordinary path is insufficient. Ask whether the user wants to continue with cp-skill-write-multistage, and invoke it only after explicit confirmation.

Step 5 - Search Before Writing

Write does not run active discovery — that is cp-skill-connect's job. Write authors one document and adds only links supplied by the user or already loaded for this write, plus a cheap duplicate guard:

1. Near-duplicate check. Search the target collection for the new document's distinctive title terms with rg (e.g. rg -i "key term" kb/theory/ --glob "*.md"). This is a targeted term search — do not enumerate the whole collection; a complete listing costs linear context and is the wrong tool for a single document's duplicate check. If a near-duplicate already exists, prefer editing it to creating a second document.
2. Context already loaded. Consider relevant documents loaded for this write, including sources and ingests, as link candidates.
3. User-named targets. Link targets the user mentions in the prompt.

In edit mode, also run a backlinks lookup on the target document — one query, no body search — so edits don't orphan dependents.

This guard is intra-KB only. Do not search the external literature for missing prior art and do not infer novelty from the absence of a named source. If the user explicitly asks whether a document duplicates, restates, or is subsumed by external literature, or asks for a literature disposition of the document on that basis, invoke cp-skill-write-multistage with the same target and request. That explicit request supplies the confirmation required by Step 4; do not ask the user to authorize the handoff again. The multistage skill loads the specialised literature-disposition procedure.

All other discovery — collection-wide description scans, cross-destination prospecting, body search, tag traversal, link-following, reverse-edge reasoning — belongs to cp-skill-connect.

Step 6 - Draft The Candidate

Follow the type-spec doc and collection conventions. Derive a lowercase-hyphenated filename from # Title unless editing an existing file. For typed documents, write the type as its spec's path under a KB root, such as types/note.md or reference/types/adr.md.

Set traits only when clearly warranted. The available traits and their meanings are defined in the target type's spec (e.g. the traits table in the note type) — take the vocabulary from there, not from a remembered list.

Preserve existing frontmatter and links during edits unless the requested change requires changing them.