wiki-authoring

name	wiki-authoring
description	Use when creating or updating source-backed DB wiki pages — selecting entity/concept/decision/question/improvement/checklist/summary types, applying frontmatter schemas, validating wikilinks, and submitting writes through kb-mcp tools.

Wiki Authoring

Use this skill as the runtime contract for raw-to-wiki authoring. DB rows are the source of truth; Markdown under data/ is generated export. Do not look for a workflow doc during execution; this skill is the complete operating surface.

Evidence-derived only. This skill is for pages grounded in a data/raw source — including all LLM/cron authoring, which MUST cite real sources. For a first-party human note with no external source, use the wiki-note skill (origin: authored, sources: []); do not fake a citation here.

Rules

• Never modify existing exported files under data/raw/.
• Every wiki page must cite sources: paths relative to data/, for example raw/github/issues/repo_42.md.
• Never use data/raw/... or absolute paths in sources:.
• Use wikilinks only to existing file stems. aliases: do not satisfy lint.
• Do not use the reserved ## User Feedback heading in authored content.
• New entity, concept, decision, improvement, checklist, and question pages start with review_status: not_processed.
• If semantically editing an approved page, reset review_status: not_processed; keep approved only for typo/format-only edits.

Bundled Templates

Copy from reference/templates/:

entity.md
concept.md
decision.md
question.md
improvement.md
checklist.md
summaries/weekly.md
summaries/monthly.md

Daily summaries do not need a separate template; use the summary schema below.

Pipeline

1. Select source evidence
2. Choose wiki type and path
3. Copy or follow the matching template
4. Fill frontmatter and body from sources only
5. Call the kb-mcp `upsert_page` tool (create or update by slug) or `patch_page` tool (partial update)
6. Call the kb-mcp `create_operation_log` tool for the operation note
7. Confirm the tool result reports `export.status == success`; on an `error`/`code` result handle it (lint_failed → fix frontmatter/body and retry; conflict → already exists; not_found → wrong slug)

Type And Path

Type	Path	Use for
entity	data/wiki/entities/<subject>/YYYY-MM/<stem>.md	named project, repo, PR, issue, person, tool, event
concept	data/wiki/concepts/<stem>.md	reusable idea, pattern, protocol
decision	data/wiki/decisions/YYYY-MM-DD-<slug>.md	closed choice with rationale
question	data/wiki/questions/<stem>.md	reusable Q&A
improvement	data/wiki/improvements/YYYY-MM/<stem>.md	open issue, proposal, improvement
checklist	data/wiki/checklists/<stem>.md	repeatable procedure
summary	export path wiki/summaries/YYYY/MM/<period>-<kind>.md	daily/weekly/monthly rollup

Use stable ASCII slugs unless an existing local convention requires otherwise.

Frontmatter Schemas

entity / concept / question

---
type: entity
review_status: not_processed
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
sources:
  - raw/...
aliases: []
tags: []
---

Use type: concept or type: question as appropriate. aliases: is required for entity and concept templates; keep it harmless on question pages if the copied template includes it.

decision

---
type: decision
review_status: not_processed
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
sources:
  - raw/...
tags: [decision]
---

Filename must carry the decision date: YYYY-MM-DD-<slug>.md.

improvement

---
type: improvement
review_status: not_processed
kind: improvement
observed_at: "YYYY-MM-DD"
domain: dx
severity: med
issue_status: open
related: []
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
sources:
  - raw/...
tags: []
---

Enums:

• kind: improvement | issue | proposal
• domain: cost | correctness | perf | dx | security
• severity: low | med | high
• issue_status: open | acknowledged | resolved | wontfix

checklist

---
type: checklist
review_status: not_processed
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
sources:
  - raw/...
tags: []
---

Body must include ## Items with task-list syntax:

## Items

- [ ] First repeatable action

summary

---
type: summary
subtype: daily
date: "YYYY-MM-DD"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
sources:
  - raw/...
tags: []
---

Weekly/monthly summaries use period_start and period_end; weekly also has week: "YYYY-WNN" and monthly month: "YYYY-MM". Summaries do not use review_status.

Promotion Criteria

Create an atomic wiki page only when the content has durable future value. Otherwise keep it in the period summary or handoff.

Target	Promote when
entity	named thing will need future lookup
concept	pattern repeats or explains reusable behavior
decision	choice is closed and rationale is captured
question	Q&A is complete and likely to recur
improvement	unresolved actionable work exists
checklist	procedure should be repeated

DB Write Contract

Writes go through kb-mcp tools (registered in the opencode run session). For a new page or a full rewrite, call the kb-mcp upsert_page tool with structured args:

• frontmatter — an object/dict (NOT yaml text)
• body_md — the body without the --- fence
• slug, type, export_path

Optional: title, category, review_status, origin, created_at, updated_at, source. For a partial update to an existing page, call the kb-mcp patch_page tool with slug plus only the fields to change (title, body_md, frontmatter, category, review_status, source, note).

The tool appends a revision and exports Markdown immediately. Do not manually regenerate INDEX.md; it is generated export from the DB.

Reads stay on psql "$DATABASE_URL" -tAc "<SELECT ...>" (or the read-only kb-mcp query_sql tool).

Common fixes:

Error	Fix
INDEX.md: stale	DB export owns generated files; INDEX.md is regenerated on DB write
source not found	remove data/ prefix; verify path exists under data/
dead wikilink	link to exact file stem or use plain text
improvement missing fields	fill all six improvement-specific fields
checklist missing items	add ## Items with - [ ] tasks
raw immutability violation	do not edit raw; report the external blocker

Log Format

Call the kb-mcp create_operation_log tool with this body_md:

## YYYY-MM-DD (wiki authoring)

- **sources**: raw/...
- **created/updated**: wiki/...
- **review_status**: not_processed
- **db_write**: page export succeeded

Red Flags

• About to author from memory without a cited source path.
• About to create a wikilink to a page that does not exist.
• About to write an improvement without kind, observed_at, domain, severity, issue_status, and related.
• About to lint before DB write — the kb-mcp upsert_page tool validates on submission (returns code: lint_failed on failure); INDEX.md is regenerated automatically.