chapterhouse 0.3.15 → 0.3.17

package/skills/wiki-conventions/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: wiki-conventions
+description: Use when creating, editing, linting, restructuring, or reviewing Chapterhouse wiki content.
+when_to_load: Wiki tools, remember/forget workflows, or direct edits under the Chapterhouse wiki.
+related_skills:
+  - squad
+---
+
+# Wiki Conventions
+
+Use this skill before creating, editing, linting, restructuring, archiving, or reviewing Chapterhouse wiki content.
+
+## Orientation Ritual — Mandatory Before Any Wiki Write
+
+Perform this checklist before using `wiki_update`, `remember`, `forget`, `wiki_ingest`, `wiki_lint`, or `wiki_rebuild_index`:
+
+1. Read `pages/index.md` with `wiki_read`.
+2. Scan the last 20-30 entries of `pages/_meta/log.md` to see recent edits, archives, and reorganizations.
+3. If the wiki is large, the topic is ambiguous, or you might be creating a page, run `wiki_search` for the topic first.
+
+Do not skip the ritual because the task feels small. The point is to avoid duplicate pages, category mistakes, stale contradictions, and taxonomy drift.
+
+## Wiki Structure Recap
+
+- **Entity categories** live at `pages/<category>/<topic>/index.md` with optional facet pages beside the overview.
+- **Flat categories** live in a single page such as `pages/preferences.md`, `pages/facts.md`, or `pages/routines.md`.
+- **Decisions** always belong to an entity and should land in `pages/<entity-category>/<topic>/decisions.md`.
+
+## Naming Conventions
+
+- Use lowercase only.
+- Use kebab-case slugs.
+- Do not put dates in slugs.
+- Keep facet names predictable and durable, such as `decisions`, `feature-ideas`, or `architecture`.
+- If a name feels ad hoc, it probably belongs as a section on an existing page instead of a new facet.
+
+## `index.md` vs Facet Pages
+
+- Use `index.md` for the durable overview of a topic, entity, or area.
+- Use a facet page only when the subtopic has ongoing value and a stable identity.
+- Do not create a facet page as random overflow for a page that merely feels long today.
+- If a page is growing because it contains several durable subtopics, split those into facets and keep `index.md` as the orientation page.
+
+## Page Creation Thresholds
+
+- Create a new page when a topic appears in two or more distinct sources or interactions.
+- Create a new page when the topic is central to one major source, even if it is only one source so far.
+- Add to an existing page when coverage already exists.
+- Do not create a page for a passing mention, transient detail, or one-off aside.
+- Split pages once they approach roughly 300 lines.
+- Archive fully superseded pages into `pages/_archive/` and remove them from the active index rather than letting stale content linger in place.
+
+## Decision Recording Protocol
+
+- With `remember`, use `category: "decision"` plus both `about` and `entity`.
+- Record the decision against the actual entity that owns it.
+- Keep decision facets canonical; prefer `decisions.md` over inventing one-off decision page names.
+
+## Cross-Reference Standards
+
+- Prefer wiki-relative paths over raw URLs when a wiki page exists.
+- Avoid raw local absolute paths in the body when a canonical wiki page can be linked instead.
+- Add reciprocal links when the relationship is durable enough that future readers should discover it from either side.
+
+## Tag Usage
+
+- Treat the merged taxonomy as the source of truth: code-defined defaults plus optional `pages/_meta/taxonomy.md` extensions.
+- Read `pages/_meta/taxonomy.md` before inventing a new tag.
+- If a new durable tag is needed, extend `pages/_meta/taxonomy.md` first instead of inventing the tag inline on a page.
+
+## Contradiction Update Policy
+
+When two sources disagree:
+
+1. Compare dates first.
+2. If the conflict is real, preserve both claims instead of collapsing them into one "truth".
+3. Keep dates, sources, or citations in the page body so the disagreement is auditable.
+4. Add reciprocal `contradictions:` frontmatter references.
+5. Set `contested: true` while the issue remains unresolved.
+6. Use `confidence` to describe certainty; do not smooth over disagreement with vague prose.
+
+## Tone
+
+- Be terse.
+- Be factual.
+- Be dated when the timing matters.
+- Avoid speculative voice such as "I think" unless the uncertainty itself is the fact being recorded.
+- Prefer explicit source attribution over implied certainty.
+
+## Frontmatter Shape
+
+Required fields:
+
+```yaml
+---
+title: Chapterhouse
+summary: Team-level AI assistant for engineering teams.
+---
+```
+
+Recommended fields for most durable pages:
+
+```yaml
+---
+title: Chapterhouse
+summary: Team-level AI assistant for engineering teams.
+updated: 2026-05-12
+tags: [engineering, orchestration]
+related: [pages/projects/chapterhouse/decisions.md]
+---
+```
+
+Use contradiction-supporting fields when needed:
+
+```yaml
+---
+title: Chapterhouse
+summary: Coordination notes about the runtime architecture.
+updated: 2026-05-12
+tags: [engineering, architecture]
+related: [pages/projects/chapterhouse/index.md]
+confidence: low
+contested: true
+contradictions: [pages/projects/chapterhouse/decisions.md]
+---
+```
+
+Use `autostub: true` only for genuine stubs that are intentionally thin and expected to grow later.
+
+## Common Mistakes
+
+- **Wrong category:** move the content to the correct entity or flat page instead of stretching the path rules.
+- **Page created too early:** merge it into an existing page or section until the topic earns a standalone page.
+- **Invented tag:** update `pages/_meta/taxonomy.md` first.
+- **Skipped orientation ritual:** stop, orient, then retry.
+- **Collapsed contradiction:** preserve both claims, date them, and mark the relationship explicitly.
+
+## Routing Guide — "I want to record X. Where does it go?"
+
+- A durable fact about a named project, tool, person, org, topic, or area -> `pages/<category>/<slug>/index.md`
+- A durable subtopic of an existing entity -> `pages/<category>/<slug>/<facet>.md`
+- A decision about an entity -> `remember` with `category: "decision"`, `about`, and `entity`, or write to that entity's `decisions.md`
+- A user preference or routine -> the corresponding flat category page
+- Source material you want preserved before synthesis -> `wiki_ingest`
+- A passing mention with no durable value yet -> do not create a new page; add it to existing context or leave it out