kthneighbor/corpus-convention / corpus-document-lifecycle
corpus-document-lifecycle
VerifiedGoverns ALL operations that create or modify markdown files in the corpus — creating notes, research outputs, or reference documents; editing or restructuring existing documents; processing external content into the corpus. Enforces the Corpus Documentation Convention — frontmatter on creation, the epistemic-status regression rule on AI edits, surgical-edit-over-regeneration default, and provenance preservation. Trigger on any request to create, update, edit, add to, summarize into, or reorganize a document in the corpus.
Corpus Document Lifecycle Skill
This skill provides the standard protocol for creating, updating, and regenerating documents in a markdown corpus. It operationalizes the Corpus Documentation Convention, which should be kept alongside the corpus and read when its specifics are needed; where this skill is silent, the Convention governs.
Pre-Flight Protocol
Before any document operation, establish:
- Operation type: CREATE | UPDATE | REGENERATE
- Document identity: name, current version, target version
- Current frontmatter state: read the target document's frontmatter in full. Note
epistemic_status,version,last_modified,information_classification, and anydependencies/relatedfields. - Change scope: what specifically is changing vs. preserved
- Source materials: what inputs inform this operation
If any of these are unclear, ask the operator for clarification before proceeding.
Operation Mode Selection
Before modifying a document, determine the appropriate mode:
Use EDIT (surgical, targeted changes) when:
- Changes are localized to specific sections
- Adding new content without restructuring
- Fixing errors, typos, or small updates
- Preserving exact formatting elsewhere matters
- The document is substantial and less than ~30% is changing
Use REGENERATE (rewrite) only when:
- Major structural reorganization is required
- More than ~50% of content is changing
- The operator explicitly requests "rewrite" / "new version"
- The document is short (<200 lines) and changes are pervasive
The line counts and percentages above are defaults calibrated for substantial documents. In a corpus of short notes, <200 lines would license regeneration everywhere and defeat the point; scale the thresholds to the corpus rather than applying them literally. The bias, not the number, is what matters.
State Your Choice
Before executing, explicitly state the mode and why:
"I'll EDIT this document (surgical changes to Section X) rather than
regenerate, to minimize information-loss risk."
or
"I'll REGENERATE this document because [structural change / >50% changing /
operator requested rewrite]. Preservation protocol applies to everything
not slated to change."
The default bias is strong: when in doubt, EDIT. Regeneration silently discards nuance; requiring a stated decision to regenerate is the guardrail.
Document Operation Protocol
Step 1: Source Review
- Read the source document(s) completely
- Note current structure (sections, subsections)
- Identify all cross-references and wiki-links (internal and external)
- Note all frontmatter fields and values
Step 2: Change Application
- Apply requested changes precisely
- For content NOT explicitly requested to change: PRESERVE EXACTLY
- When in doubt whether something should change: DON'T CHANGE IT
- Never strip sources, citations, or provenance fields — provenance is permanent. When summarizing or transforming external content, record the source in the result (the Convention's optional
sourcesfield, or inline where that reads better) - Flag any ambiguities for operator confirmation
Step 3: Frontmatter Update — including the Regression Rule
Always update:
last_modified: [current date, YYYY-MM-DD]
version: [bump if the change is substantive — see Convention §2]
The Regression Rule (mandatory, no exceptions): if the document's epistemic_status is human-reviewed or human-cleared and this operation changes its content:
- Set
epistemic_status: ai-generated - Leave
last_human_reviewuntouched — it records human activity, not AI activity - Notify the operator explicitly in your reply that the regression occurred and why
Never silently edit a human-reviewed or human-cleared document without regressing its status. A stale trust marker on AI-changed content is worse than no marker.
For CREATE operations: apply full frontmatter per the Convention §1. Minimum: title, type, status, sensitivity, information_classification, version, created, last_modified, epistemic_status: ai-generated, generating_model. Never create a corpus file without frontmatter.
Step 4: Self-Containment Check
The document must be fully self-contained:
- No "see previous version for X" references
- No dangling cross-references to removed content
- All context necessary for comprehension is present
Verification Protocol
Execute multi-way verification before presenting output:
Method 1: Checklist Verification
- All requested changes are present
- Frontmatter updated (
last_modified,versionif substantive) - Regression rule applied if triggered, and operator notified
- Self-contained (no prior-version references)
Method 2: Structural Verification
- All sections from the source present (unless explicitly removed)
- Section numbering coherent
- Any table of contents matches actual sections
Method 3: Cross-Reference Verification
- All internal links and wiki-links valid
- All external references still accurate
- No orphaned references to removed content
Method 4: Diff Verification
- Every change from source is deliberate (requested)
- No accidental deletions
- No accidental additions
Report verification results explicitly — in the conversation.
Output Protocol
- Report the operation performed, the mode used, and verification results in the conversation
- If the regression rule fired, state it prominently
- Provide a change summary table in the conversation:
| Change Type | Location | Description |
|-------------|----------|-------------|
| ADD | Section X | New subsection on Y |
| UPDATE | Section Z | Revised wording |
| REMOVE | Section W | Consolidated into X |
| PRESERVE | All other | No changes |
Session output stays in the session. Verification reports, change-summary tables, and ripple-effect notes are NEVER embedded in the document itself. They serve the editing process, not the document's content, and they go stale the moment the session ends. What belongs in the document: changelog entries (factual, terse, per Convention §4), recorded decisions, open questions. The test: would a reader six months from now benefit from this content inside the document? If no, it is session output.
Relationship Awareness
Pre-Operation: Understand Context
Read the target document's frontmatter relationship fields (dependencies, references, related). Ask:
- Have any dependencies changed more recently than this document's
last_modified? If so, flag possible staleness before editing. - Will these changes affect documents that reference this one?
Post-Operation: Flag Ripple Effects
In the conversation (never in the document), note potential impacts:
### Potential Ripple Effects
- **Dependencies**: this document depends on [X, Y] — verify alignment
- **Referenced by**: documents linking here may need review
- **Related**: consider whether [Z] needs corresponding updates
Do not act on other documents unprompted; surface the ripple and let the operator decide.
Error Prevention
Guard against these failure modes:
- Content loss — source information missing from output. Prevention: explicit preservation check (Step 2, Method 4).
- Silent trust-marker staleness — editing a reviewed document without regression. Prevention: Step 3 regression rule + operator notification.
- Regeneration when editing would do — nuance silently discarded. Prevention: stated mode selection with the EDIT default.
- Provenance stripping — sources lost in transformation. Prevention: Step 2 rule 4.
- Version confusion — wrong version numbers. Prevention: pre-flight identity check.
- Dangling references — links to removed content. Prevention: Method 3.
- Scope creep — changing things not requested. Prevention: "when in doubt, preserve."
- Context pollution — session output or prior-version references embedded in the document. Prevention: self-containment check + output protocol.
This skill governs all corpus document lifecycle operations. For the metadata standard itself, see the Corpus Documentation Convention, which is versioned independently of this skill.
Skill version 0.4. This file carries no document frontmatter: an agent skill's frontmatter schema is fixed by the runtime that loads it, so the Convention's document fields cannot be applied here. The exemption is deliberate and is encoded in the accompanying validator.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |