humansys/raise/rai-docs-update

Docs Update

Purpose

Close the coherence loop between code and architecture docs. Compare knowledge graph truth against module doc frontmatter, update drifted fields, and optionally refresh narrative sections. Since 2.1.0 (S15884.2), this also drives Layer 2 — synthesizing a flowchart TD C4-shaped diagram + narrative per module into a delimited rai:auto region (ADR-146), gated through the same HITL review as the rest of this skill.

No LLM call happens inside raise_cli — the CLI layer (rai docs architecture ...) only assembles input, validates dialect, and writes/reads regions. Step 3.5 below is the one place synthesis happens: one agent turn, consuming a pre-packed bundle.

Mastery Levels (ShuHaRi)

• Shu: Present every diff, ask before every change
• Ha: Batch frontmatter changes with single HITL gate, narrative only for structural changes
• Ri: Autonomous frontmatter updates, HITL only for narrative

Context

When to use: After stories that changed code structure, during /rai-story-close, after discovery refresh.

When to skip: Stories that only changed tests/docs/non-code. No graph available.

Inputs: Knowledge graph (.raise/rai/memory/index.json), module docs (governance/architecture/modules/*.md).

Steps

Step 1: Build Graph & Identify Affected Modules

rai graph build

Read .raise/rai/personal/last-diff.json for changed modules. If no diff or no affected_modules, check all modules.

Layer 2 work set (S15884.2): for each module doc under governance/architecture/modules/*.md that carries a rai:auto region, compute the current bundle fingerprint and compare it to the region's stored src:

rai docs architecture bundle --module mod-{package}--{name} --format json   # inspect, or just diff via status:
rai docs architecture status

{package} is the doc's own package: frontmatter field (e.g. raise-cli, raise-server) — module ids are package-qualified since RAISE-16033, so mod-{name} alone will not resolve.

rai docs architecture status reports fresh/stale per doc without needing to hand-parse fingerprints. Layer 2's work set = fingerprint-changed docs — a subset of affected_modules above, since graph churn that does not change the semantic bundle (e.g. only volatile fields moved) is filtered out here, before any synthesis cost is incurred. Docs with no rai:auto region yet (the 22 pre-existing module docs) are eligible for first insertion — treat them as part of the work set too when their frontmatter-level affected_modules diff says they changed.

<verification> Module list identified for comparison. Layer 2 work set (fingerprint-changed or first-insertion docs) identified separately from the frontmatter-only affected_modules list. </verification>

Step 2: Compare Frontmatter Per Module

Use raise_graph_context MCP tool with module_id="mod-{package}--{name}", cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to: rai graph context mod-{package}--{name} --format json

Compare doc-declared vs code-truth:

Fields the skill MUST NOT touch: purpose, constraints, status, entry_points, name, type.

<verification> Drifted fields identified per module. </verification>

Step 3: HITL Gate — Apply Frontmatter

Present drift report:

### mod-raise-cli--memory
  depends_on: [config] → [config, schemas]  (added: schemas)
  components: 30 → 34

Ask: "Apply frontmatter updates to N modules? [y/n/selective]"

Apply changes to YAML frontmatter only — preserve all other content and field ordering.

<verification> Frontmatter updates applied (or skipped by user). </verification>

Step 3.5: Layer 2 Synthesis (NEW, S15884.2)

Runs after Step 3 so the bundle and frontmatter agree with each other. For each doc in the Layer 2 work set identified in Step 1:

1. Read the bundle — the entire synthesis input, one payload, no follow-up graph queries:

``bash rai docs architecture bundle --module mod-{package}--{name} --format json ``

1. Synthesize in one turn — a flowchart TD diagram using C4-shaped subgraph conventions (boundary = subgraph, element = node, relationship = labeled edge) plus a short narrative paragraph. This is the only LLM call in the entire pipeline (D-S2) — no multi-turn refinement, no per-node calls. flowchart+subgraph is the only allowed dialect; do not emit C4Context/C4Container/C4Component/architecture-beta — they are rejected by the next step and were never confirmed to render on all four targets (RAISE-15886 T4).
2. Validate the dialect before writing anything:

``bash rai docs architecture validate --stdin <<< "$SYNTHESIZED_MARKDOWN" `` A non-zero exit means the synthesis produced a disallowed dialect — retry synthesis in the same turn (re-shape the same content as flowchart), do not write rejected content.

1. Check for hand-tampering before staging — if this reports a content-hash mismatch, a human edited inside the region since the last run. Surface that warning in the Step 4 diff below rather than silently overwriting:

``bash rai docs architecture region check --file governance/architecture/modules/{name}.md ``

1. Stage the write with `--dry-run` — this computes the would-be diff (idempotent by construction: an unchanged bundle against an unchanged src stages as "unchanged", no write pending) but writes nothing to disk:

``bash rai docs architecture region write \ --file governance/architecture/modules/{name}.md \ --id c4-component --src <bundle-fingerprint-from-step-1> \ --stdin --dry-run <<< "$SYNTHESIZED_MARKDOWN" ``

Region diffs produced here are staged only — --dry-run guarantees no code path in this step touches disk. They flow into Step 4's existing HITL gate as the diff to review, same as frontmatter and narrative changes. Step 4 issues the real (non-dry-run) region write call — that is the only point in the whole pipeline that commits generated content to disk.

<verification> Work-set docs have a synthesized flowchart+narrative region diff staged via --dry-run (or skipped where the bundle was unchanged — the common case in steady state). Nothing written to disk yet. </verification>

Step 3.7: Package Diagram Freshness (S15884.5, RAISE-16328)

Run the read-only check — this step never writes anything:

uv run python scripts/regen-architecture-diagrams.py --check \
  --component raise-server --component raise-cli

Raise-admin is intentionally excluded here: its extraction requires madge/npx (an optional Node dep), and including it would allow an unverifiable exit 3 to mask a real stale or fidelity failure for raise-server/raise-cli (D8 precedence: exit 3 > exit 1/2). Raise-admin is handled separately at the end if npx is available.

Raise-admin (optional): if npx is available, also run:

uv run python scripts/regen-architecture-diagrams.py --check --component raise-admin

Exit code 3 here = "unverifiable, skip Trigger D for admin"; exit 2 = add raise-admin to Trigger D components.

This step is read-only. Regeneration runs in Step 4 only, after approval. Never call regen mode here.

<verification> Package diagram freshness checked. Stale components (if any) noted for Step 4 Trigger D. Nothing written to disk. </verification>

Step 4: Narrative Review (if triggered)

Trigger A (full review): New/removed modules, major dependency changes (>2), significant API changes (>5).

Trigger B (targeted scan): For any frontmatter change, scan prose for stale hardcoded values (old counts, removed dependency names, removed API names). These are mechanical text fixes.

Trigger C (region diffs, S15884.2): Any rai:auto region staged in Step 3.5 via --dry-run — diagram inserted, replaced, or flagged with a hand-tampering warning. This is the same HITL gate as Trigger A/B, not a second gate — region diffs are bounded to one block per doc (ADR-146's whole point), so they are cheap to review alongside the mechanical text fixes.

Trigger D (package diagram staleness, S15884.5): One or more package-level architecture diagrams reported stale by Step 3.7 (--check exit 2). This is the same HITL gate as A/B/C — stale component names are listed alongside any other proposed changes. On approval, run regen mode for the named stale components:

uv run python scripts/regen-architecture-diagrams.py --component <stale-component>

The script writes manifest + mmd + html, then runs the full fidelity check — exits non-zero on any fidelity error. Show the verify output and git diff --stat of regen'd files before staging.

Present proposed changes as diff — mechanical text fixes and the --dry-run region previews together. Ask: "Apply these changes? [y/n/selective]"

Only after approval, commit each approved region by re-running Step 3.5's exact command WITHOUT --dry-run:

rai docs architecture region write \
  --file governance/architecture/modules/{name}.md \
  --id c4-component --src <bundle-fingerprint-from-step-1> \
  --stdin <<< "$SYNTHESIZED_MARKDOWN"

This is the one and only point in the pipeline that calls path.write_text on a module doc for generated region content (AC8) — no code path writes and publishes generated region content without this gate: --dry-run in Step 3.5 never touches disk, and this call only runs after a human said yes.

<verification> Narrative changes applied or no triggers found. Region diffs (if any) reviewed through this same gate, then committed to disk via the non-dry-run region write call — never before approval. </verification>

Step 5: Rebuild & Summarize

If any changes applied:

rai graph build

For each module updated in this run, re-publish to docs adapter:

Use raise_docs_write MCP tool with doc_type="architecture-module", title="{name}", content="existing governance/architecture/modules/{name}.md contents (updated)", output_path="governance/architecture/modules/{name}.md", cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to:

rai docs write architecture-module \
  --title "{name}" \
  --stdin \
  --output-path governance/architecture/modules/{name}.md << EOF
$(cat governance/architecture/modules/{name}.md)
EOF

Note: heredoc without quotes so $(cat ...) expands the updated file content.

Pre-flight check (D-S7, AC11): before publishing any doc whose body now contains a mermaid fence, verify the target Confluence space has the Mermaid macro app installed and licensed. If the capability check fails, stop with an actionable message — do not publish a page that will render as an unknown-macro error. This does not touch the mermaid_macro=False fallback branch (that stays a follow-up story); it only adds the pre-flight check in front of the existing hard-True publish path.

Present summary: modules checked, frontmatter updated, narrative updated, regions written, graph rebuilt.