docs(agents): fix critic-identified gaps in memory and skillbook agents

## Memory Agent (src/claude/memory.md)
- Add Create vs Update Decision flowchart
- Add Domain Selection table for index routing
- Fix table row insertion: warn about delimiter row, insert after LAST DATA row
- Add File Naming vs Entity IDs section with mapping table
- Add Relations encoding section with markdown syntax

## Skillbook Agent (src/claude/skillbook.md)
[Changes from prior commit already included]

## New Skill: Skill-Documentation-008
- Amnesiac-Proof Documentation Verification Protocol
- 5-step critic verification process before committing agent docs
- Impact: 10/10, Tags: #P0, #BLOCKING

## Verification
- [PASS] Critic verification on memory.md (6/6 questions passed)
- [PASS] Critic verification on skillbook.md (4/4 questions passed)
- [PASS] Memory index validation (30/30 domains)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rjmurillo-bot

.serena/memories/documentation-verification-protocol.md

@@ -0,0 +1,85 @@
+# Skill-Documentation-008: Amnesiac-Proof Documentation Verification
+
+**Statement**: Verify agent documentation with critic before commit using amnesiac execution test.
+
+**Context**: After updating agent documentation (*.md files in src/claude/, templates/agents/, AGENTS.md, or .agents/agents/)
+
+**Evidence**: Session 2025-12-23 (Issue #307) - Critic verification caught 4 gaps in skillbook.md and 5 gaps in memory.md before commit. All [FAIL] items converted to [PASS] with objective fixes.
+
+**Atomicity**: 98% | **Impact**: 10/10
+
+**Tags**: #P0, #BLOCKING (for documentation quality)
+
+## Pattern
+
+Before committing agent documentation, run this 5-step protocol:
+
+### Step 1: Self-Review
+
+Ask: "What would an amnesiac agent NOT know from this documentation?"
+
+List specific gaps (file naming, numbering, decision criteria, etc.)
+
+### Step 2: Invoke Critic
+
+```python
+Task(
+    subagent_type="critic",
+    prompt="""Review [file] for completeness. An amnesiac agent will read ONLY this file.
+
+    Can they:
+    1. [Specific capability question 1]
+    2. [Specific capability question 2]
+    3. [...]
+
+    Report [PASS]/[FAIL] for each with objective gap identification."""
+)
+```
+
+### Step 3: Fix All [FAIL] Items
+
+For each [FAIL], apply objective fixes:
+
+| Gap Type | Fix Pattern |
+|----------|-------------|
+| Undefined criteria | Add decision tree with explicit branches |
+| Missing procedure | Add numbered steps with actual commands |
+| Vague terms | Replace with quantified thresholds or mapping tables |
+| Ambiguous references | Add grep commands or file path examples |
+
+**Required fix quality**:
+- NOT "when appropriate" → INSTEAD "when X > threshold Y"
+- NOT "similar to" → INSTEAD "grep command: `grep -r 'pattern' path/`"
+- NOT "as needed" → INSTEAD "if condition A then action B, else action C"
+
+### Step 4: Re-Run Critic
+
+Invoke critic again with same questions. Repeat Step 3 until all [PASS].
+
+### Step 5: Commit With Verification Evidence
+
+Include in commit message:
+```
+[PASS] Critic verification: all amnesiac execution tests
+
+Verified: [list of capability questions]
+```
+
+## Anti-Pattern
+
+**NEVER**:
+- Commit documentation without critic verification
+- Accept vague terms ("when appropriate", "as needed", "similar to")
+- Assume prior context will be available to future agents
+
+**Example of vague (REJECT)**:
+> "Choose the appropriate index for your skill"
+
+**Example of objective (ACCEPT)**:
+> "Match skill keywords to memory-index.md Task Keywords column. If >50% overlap exists, use that domain's index. If <50% overlap AND 5+ skills expected, create new domain index. Else use closest related domain."
+
+## Related
+
+- **ENABLES**: Skill-Documentation-007 (provides HOW to achieve self-containment principle)
+- **ENABLES**: All agent documentation updates
+- **REFERENCES**: Skill-Quality-002 (QA routing pattern, critic-as-gate)

.serena/memories/skills-documentation-index.md

@@ -14,11 +14,12 @@
 | self-contained artifact handoff agent amnesia autonomous | documentation-self-contained |
 | skill format standalone bundled decision tree mermaid P0 | skill-format-selection-decision-tree |
 | index selection domain routing keyword overlap create new | skill-index-selection-decision-tree |
+| verification critic amnesiac completeness objective PASS FAIL protocol | documentation-verification-protocol |
 
 ## Domain Statistics
 
-- **Skills**: 7 core skills
-- **CRITICAL Tags**: 2 (user-facing restrictions, self-containment)
+- **Skills**: 8 core skills
+- **CRITICAL Tags**: 3 (user-facing restrictions, self-containment, verification protocol)
 
 ## See Also
 

src/claude/memory.md

@@ -253,9 +253,14 @@ content: "# [Title]\n\n**Statement**: [Atomic description]\n\n**Context**: [When
 # Step 2: Read domain index to find last table row
 mcp__serena__read_memory
 memory_file_name: "skills-[domain]-index"
-# Find the LAST row in the Activation Vocabulary table
-
-# Step 3: Insert new row AFTER the last existing row
+# WARNING: Markdown tables have structure:
+#   | Keywords | File |           <-- Header row
+#   |----------|------|           <-- Delimiter row (SKIP THIS)
+#   | existing | file |           <-- Data rows
+# Find the LAST DATA ROW (not header, not delimiter)
+# Inserting after header/delimiter corrupts the table
+
+# Step 3: Insert new row AFTER the last existing DATA row
 mcp__serena__edit_memory
 memory_file_name: "skills-[domain]-index"
 needle: "| [last-existing-keywords] | [last-existing-file] |"

src/copilot-cli/memory.agent.md

@@ -199,9 +199,14 @@ content: "# [Title]\n\n**Statement**: [Atomic description]\n\n**Context**: [When
 # Step 2: Read domain index to find last table row
 serena/read_memory
 memory_file_name: "skills-[domain]-index"
-# Find the LAST row in the Activation Vocabulary table
-
-# Step 3: Insert new row AFTER the last existing row
+# WARNING: Markdown tables have structure:
+#   | Keywords | File |           <-- Header row
+#   |----------|------|           <-- Delimiter row (SKIP THIS)
+#   | existing | file |           <-- Data rows
+# Find the LAST DATA ROW (not header, not delimiter)
+# Inserting after header/delimiter corrupts the table
+
+# Step 3: Insert new row AFTER the last existing DATA row
 serena/edit_memory
 memory_file_name: "skills-[domain]-index"
 needle: "| [last-existing-keywords] | [last-existing-file] |"

src/vs-code-agents/memory.agent.md

@@ -199,9 +199,14 @@ content: "# [Title]\n\n**Statement**: [Atomic description]\n\n**Context**: [When
 # Step 2: Read domain index to find last table row
 serena/read_memory
 memory_file_name: "skills-[domain]-index"
-# Find the LAST row in the Activation Vocabulary table
-
-# Step 3: Insert new row AFTER the last existing row
+# WARNING: Markdown tables have structure:
+#   | Keywords | File |           <-- Header row
+#   |----------|------|           <-- Delimiter row (SKIP THIS)
+#   | existing | file |           <-- Data rows
+# Find the LAST DATA ROW (not header, not delimiter)
+# Inserting after header/delimiter corrupts the table
+
+# Step 3: Insert new row AFTER the last existing DATA row
 serena/edit_memory
 memory_file_name: "skills-[domain]-index"
 needle: "| [last-existing-keywords] | [last-existing-file] |"

templates/agents/memory.shared.md

@@ -199,9 +199,14 @@ content: "# [Title]\n\n**Statement**: [Atomic description]\n\n**Context**: [When
 # Step 2: Read domain index to find last table row
 serena/read_memory
 memory_file_name: "skills-[domain]-index"
-# Find the LAST row in the Activation Vocabulary table
-
-# Step 3: Insert new row AFTER the last existing row
+# WARNING: Markdown tables have structure:
+#   | Keywords | File |           <-- Header row
+#   |----------|------|           <-- Delimiter row (SKIP THIS)
+#   | existing | file |           <-- Data rows
+# Find the LAST DATA ROW (not header, not delimiter)
+# Inserting after header/delimiter corrupts the table
+
+# Step 3: Insert new row AFTER the last existing DATA row
 serena/edit_memory
 memory_file_name: "skills-[domain]-index"
 needle: "| [last-existing-keywords] | [last-existing-file] |"