| name | wal-documentation-rules |
| description | Governs WAL fragment writes (domain/api/rules/data/architecture) at Archive. TRIGGER: STANDARD Archive, dimensions elected via h-archive. NOT FOR: PATCH; wiki authoring (use documentation-curator). |
Write-Ahead Log (WAL) Documentation Capture
Trigger: Invoke during the Archive Phase (STANDARD tasks only). NOT invoked for PATCH tasks (hotfix-only changes with no new domain knowledge).
When to Write WAL
| Task Type | WAL Behavior |
|---|
| STANDARD Archive (new feature, refactor, design) | User-elected — h-archive Step 3b multi-selects which dimensions to write. None is a valid choice (writes a single stub; HIGH+None requires justification). The question itself is mandatory; silent zero-WAL is not allowed. |
| PATCH Archive (hotfix, typo, config tweak) | NO — skip WAL entirely, no question asked. |
If unsure, check the task's _task_brief.md: if task_type: PATCH, skip this skill.
Why user election, not mandatory triple
The historic rule "STANDARD Archive MUST write Domain + API + Rules" pushed agents to fabricate padding fragments for tasks that genuinely touched only one dimension. The new rule trusts the user to pick; the question is enforced (you cannot silently skip), but the content is honest.
0. Single Source of Truth
- WAL + compaction policy:
.claude/workflow/ARCHIVE_WAL.md
- Write-back verification tool:
.claude/scripts/tools/writeback_gate.py
- Routing and navigation:
.claude/rules/lifecycle.md (Part 1)
1. Universal Write-back Rules (MUST)
2. Five User-Electable WAL Types (STANDARD Archive)
The user picks any subset via h-archive Step 3b. Choose Brief detail level (table-driven, ~5-15 lines) by default; only escalate to Detailed/Verbose when the user explicitly notes it.
If the user elected None, do NOT write any of the type-specific fragments below. Instead h-archive writes a single stub at .claude/wiki/wiki/domain/wal/<YYYYMMDD>_<slug>_stub.md recording the explicit decision (and a justification for HIGH risk). The stub is verified by writeback_gate.py --accept-stub.
WAL Type 1 — Domain (domain_append)
When to write: New terms, enums, roles, bounded-context concepts appear in the spec.
Output location: .claude/wiki/wiki/domain/wal/
Template:
---
origin: agent-extracted
slug: {topic}
date: {YYYY-MM-DD}
---
# Domain WAL Append - {YYYY-MM-DD} - {topic}
Source spec: `{relative_path_to_task_brief.md}`
## New / Updated Terms
| Term | Definition | Context / Usage | Confidence | Evidence |
|---|---|---|---|---|
| {term} | {one-line definition} | {which module or flow uses it} | HIGH/MEDIUM/LOW | file:line |
## New / Updated Enums
| Enum | Values | Notes | Confidence | Evidence |
|---|---|---|---|---|
| {EnumName} | `VALUE_A`, `VALUE_B` | {when each applies} | HIGH/MEDIUM/LOW | file:line |
WAL Type 2 — API (api_append)
When to write: New or changed external endpoints (method/path), request/response schema changes, auth/permission changes on endpoints.
Output location: .claude/wiki/wiki/api/wal/
Template:
---
origin: agent-extracted
slug: {topic}
date: {YYYY-MM-DD}
---
# API WAL Append - {YYYY-MM-DD} - {topic}
Source spec: `{relative_path_to_task_brief.md}`
## New / Changed Endpoints
| API (Method + Path) | Summary | Auth Required | Write-back Date |
|---|---|---|---|
| {METHOD} {/path/action} | {one-line summary} | {role or token type} | {YYYY-MM-DD} |
## Request / Response Notes (if schema changed)
- {endpoint}: request adds `{fieldName}: {type}` — {reason}
- {endpoint}: response removes `{fieldName}` — {reason}
WAL Type 3 — Rules (rules_append)
When to write: New business rules, constraints, invariants, or validation logic are codified that did not exist before.
Output location: .claude/wiki/wiki/rules/wal/
Template:
---
origin: agent-extracted
slug: {topic}
date: {YYYY-MM-DD}
---
# Rules WAL Append - {YYYY-MM-DD} - {topic}
Source spec: `{relative_path_to_task_brief.md}`
## New / Updated Rules
| Rule ID | Description | Enforcement Point | Violation Behavior | Confidence | Evidence |
|---|---|---|---|---|---|
| RULE-{NNN} | {what must/must not happen} | {controller / service / DB} | {DomainException code or DB constraint} | HIGH/MEDIUM/LOW | file:line |
WAL Type 4 — Data (data_append) — OPTIONAL
When to write: Only when the database schema changes (create/drop table, add/remove/change columns, index changes). Skip if no schema change.
Output location: .claude/wiki/wiki/data/wal/
Template:
---
origin: agent-extracted
slug: {topic}
date: {YYYY-MM-DD}
---
# Data WAL Append - {YYYY-MM-DD} - {topic}
Source spec: `{relative_path_to_task_brief.md}`
## Table Changes
| Table Name | Change Type | Key Fields / Index Notes | Notes |
|---|---|---|---|
| {table_name} | CREATE / ALTER / DROP | {key fields, indexes} | {purpose or migration note} |
## Relationship Notes (text ER, changed only)
{table_a} (N) -> {table_b} (1) via {foreign_key_column}
3. Verification Step (MUST before closing Archive)
After writing all WAL fragments, run the gate check:
python3 .claude/scripts/tools/writeback_gate.py --slug <feature_slug>
Expected output: all required WAL types listed as PRESENT. If any mandatory type is MISSING, write the missing fragment before proceeding.
Do NOT close the Archive phase until the gate passes.
4. Anti-Patterns (NEVER do these)
| Anti-Pattern | Why It Fails |
|---|
Writing raw .sql migration files to the project root | Bypasses WAL traceability; causes merge conflicts in team repos |
Editing index.md directly during automated runs | Creates Git conflicts and breaks compaction integrity |
| Writing WAL for PATCH tasks | Pollutes the wiki with trivial entries; PATCH = no WAL |
| Copy-pasting entire spec sections into WAL | WAL must be distilled facts, not raw spec content |
Skipping writeback_gate.py verification | Silent missing WAL; downstream consumers get stale data |
| Using freeform filenames (no convention) | Makes compaction impossible; files cannot be auto-discovered |
| Recording negative tool/state assertions ("X doesn't work", "无法使用") | Anti-Petrification: negative facts decay — the tool may be repaired tomorrow, leaving a stale "don't try X" warning that misleads future LLMs. Record the fix instead: fix: <command/config> or workaround: <approach>. Enforced by failure_memory.py record lint (refuses input + suggests rewrite). |
5. Merge Policy (Out of Scope for this Skill)
This skill writes only fragment files. It does NOT merge WAL into stable index.md files. Merging is handled by the compaction policy in .claude/workflow/ARCHIVE_WAL.md, triggered separately (usually by @Librarian or compactor.py).
