write-docs

name	write-docs
description	Guidelines for creating, updating, reorganizing, and reviewing Deep Cuts documentation in the project wiki, including page taxonomy, lifecycle status, protected pages, proposal handling, and link verification.

Writing and Organizing Docs

Project documentation lives in the deep-cuts wiki — a separate git repo at http://gitea:3000/botfam/deep-cuts/wiki, cloned alongside the worktrees (e.g. /Users/rlupi/src/fams/deep-cuts/wiki). Use this skill whenever you create, edit, move, classify, or review wiki pages, root docs such as README.md, or documentation-facing agent instructions.

The wiki namespace is flat (Gitea wikis have no subdirectories), so the former doc/ folder taxonomy is encoded as a slug prefix on each page. Edit docs by editing files in the wiki checkout and committing/pushing them (or via the wiki_write MCP tool / the Gitea web UI).

Start Here

1. Read the wiki Home page and _Sidebar before reorganizing or classifying docs.
2. Read the doc-lifecycle page for the current lifecycle vocabulary.
3. If the task touches multi-agent collaboration docs, also read skills/bot-collab/SKILL.md and the collab-protocol wiki page.
4. Private/blog/outreach notes are not in the wiki — they live in their own separate git repo (the former doc/private), unchanged by this workflow.

Page Taxonomy

The former folders are now slug prefixes; keep them consistent:

Prefix	Purpose
architecture-	Implemented/current technical docs and subsystem behavior.
research-	Experiments, model evaluations, analysis notes, and research trails.
proposal-	Brainstorms and unimplemented or review-needed product/technical ideas.
operations-	Process docs, reviews, cleanup notes, and maintenance guidance.
collab-	Multi-agent collaboration protocol and design docs.
session-	Collaboration session logs (session-YYYY-MM-DD-topic-slug).

When a proposal, research note, or architecture doc mixes categories, prefer preserving it and adding status/context over splitting it immediately.

For partially implemented docs, classify at the smallest useful feature slice. A single proposal can contain implemented storage, partially implemented backend commands, and unimplemented UI. Prefer a compact status table near the top over creating parallel *-implemented pages.

Backlog and review docs are different: keep the active page focused on open work. When a backlog item is completed, move it into a completion-log page (e.g. operations-*-completed-improvements), with date, commit hash, outcome, and links to changed files. Do not make future agents re-read completed recommendations unless they are looking for history.

Lifecycle Status

Each page carries a status in its frontmatter (vocabulary from the doc-lifecycle page):

• implemented: shipped or merged into the app; include code references.
• partially-implemented: meaningful parts exist, but proposal material remains.
• active-research: recent research direction or experiment trail, not product commitment.
• need-human-review: brainstorming, unimplemented, stale, mixed, or strategic enough that Roberto should decide.
• superseded: replaced by a newer doc or implementation approach.
• deferred: intentionally parked.
• rejected: evaluated and intentionally not pursued.

For unimplemented or ambiguous ideas, use need-human-review. Do not invent product priority.

Provenance Rule

Every numeric or empirical claim in a doc must be sourced or explicitly marked speculative — cite a file, an eval/metrics run, or a link, or label it a guess. Unsourced two-decimal figures (99.27%, reward tables, benchmark rates) are a confabulation smell. Flag unsourced numbers in review and require a source or a (speculative) marker.

Status ↔ Consensus (design docs under forge review)

Wiki pages have no PR gate of their own. When a design doc needs review/approval, shepherd it through a Gitea issue or PR that references the wiki page, and let the page's frontmatter status track the consensus state: need-human-review ≈ APPROVED-pending-human, accepted ≈ MERGED, superseded ≈ a decision that retired prior content. The invariant is one-directional: don't set status: accepted without a reached APPROVED state (green checks + an independent approval + no open REQUEST_CHANGES); the human accepting the decision is never blocked. See botfam:///docs/protocol §3 and botfam:///docs/review.

Protected Pages

Do not move or rewrite these without explicit approval:

• the collab-protocol wiki page
• the session-2026-06-06-sax-transformer wiki page
• skills/bot-collab/SKILL.md (still in the repo)
• models/manifest.json (app data, not a docs artifact)

Keep collaboration session-* pages as working logs unless the user explicitly asks for summarization or migration.

Writing Patterns

Architecture/current docs:

# Feature / Subsystem

## Current State
## Code Map
## Data Model / IPC
## Operational Notes
## Open Follow-Ups

Proposal docs:

# Proposal

## Status
## Problem
## Proposed UX / Behavior
## Data Model / IPC Impact
## Validation Plan
## Product-Fit Notes
## Decision Log

Research docs:

# Experiment / Research Topic

## Question
## Method
## Results
## Interpretation
## What Changed in the Product
## Remaining Unknowns

Brainstorm Handling

Many docs are intentionally exploratory. Preserve useful history, but make current state obvious:

• Add a "Current State" or "Status" section when a doc still matters.
• Add "Implemented outcome" when code diverged from the original proposal.
• Add "Superseded by" when another doc or implementation replaced the idea.
• Use superseded only when code or git history shows replacement/removal; use need-human-review for unfinished or strategically ambiguous ideas.
• Leave broad roadmap matrices as need-human-review unless Roberto explicitly promotes them.
• If you have product-fit or feasibility concerns, add them as clearly labeled notes, not as hidden rewrites.

Backlog Handling

Review, feedback, and cleanup docs are work queues, not design records. Optimize them for the next action:

• Keep only open items in the main backlog page.
• Move completed items to a nearby completion-log page such as operations-*-completed-improvements.
• Preserve enough history in the completion log to reconstruct what happened: original title, completion date, commit hash, short outcome, and links to durable docs/skills/code.
• Renumber the active backlog after moving completed sections.
• If an item is rejected or no longer desired, move it to the completion log as Rejected or Deferred with the reason rather than leaving it in the open backlog.

Link and Path Rules

Wiki pages are flat; cross-page links are by slug (no relative paths, no .md, no subdirectories):

[Architecture map](architecture-tech)

After adding or renaming pages:

1. Update links in pages that point to the renamed page, and refresh _Sidebar/Home.
2. Search for stale slugs or leftover doc/<old_path>.md references.
3. Run a local link check from the wiki checkout.

Lightweight checker (run from the wiki checkout root):

python3 - <<'PY'
import re, glob, os
LINK = re.compile(r'(?<!!)\[([^\]]+)\]\(([^)]+)\)')
pages = {os.path.basename(p)[:-3] for p in glob.glob('*.md')}
missing = []
for f in glob.glob('*.md'):
    for label, target in LINK.findall(open(f, encoding='utf-8').read()):
        if target.startswith(('http://','https://','mailto:','file://','#','botfam:')):
            continue
        slug = target.split('#',1)[0].strip()
        if not slug or '/' in slug or slug.endswith('.png'):
            continue  # external/asset/repo path — checked separately
        if slug not in pages:
            missing.append((f, label, target))
print('missing wiki links:', len(missing))
for m in missing:
    print(m)
PY

Skill Index

If you add, remove, rename, or edit frontmatter for a skill, regenerate the skill index:

tools/.venv/bin/python tools/generate_skill_index.py

Then verify skills/INDEX.md changed as expected.