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

Memory agent fixes (5 gaps -> all [FIXED]):
- Add Create vs Update Decision mermaid flowchart
- Add Domain Selection table with memory-index.md lookup
- Fix table insertion: read last row, append after (not header)
- Add File Naming vs Entity IDs clarification
- Add Relations encoding with markdown syntax

Skillbook agent fixes (4 gaps -> all [FIXED]):
- Add Skill ID Numbering procedure with grep command
- Define CRITICAL/BLOCKING criteria (Impact>=9, protocol gate, #P0)
- Clarify "Has BLOCKS/ENABLES relationships" meaning
- Fix Index Update Procedure with 3-step process

Both agents verified by critic for amnesiac agent reproducibility.

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

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

Author: rjmurillo-bot

src/claude/memory.md

@@ -121,30 +121,46 @@ mcp__serena__delete_memory
 memory_file_name: "[file-name]"
 ```
 
-## Entity Naming Conventions
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| Feature | `Feature-[Name]` | `Feature-Authentication` |
-| Module | `Module-[Name]` | `Module-Identity` |
-| Decision | `ADR-[Number]` | `ADR-001` |
-| Pattern | `Pattern-[Name]` | `Pattern-StrategyTax` |
-| Problem | `Problem-[Name]` | `Problem-CachingRace` |
-| Solution | `Solution-[Name]` | `Solution-LockingCache` |
-| Skill | `Skill-[Category]-[Number]` | `Skill-Build-001` |
-
-## Relation Types
-
-| Relation | Meaning |
-|----------|---------|
-| `implemented_in` | Feature in module |
-| `depends_on` | Entity requires another |
-| `replaces` | New replaces old |
-| `supersedes` | Newer version |
-| `related_to` | General association |
-| `blocked_by` | Progress blocked |
-| `solved_by` | Problem has solution |
-| `derived_from` | Skill from learning |
+## File Naming vs Entity IDs
+
+**File Names** (Serena storage):
+
+- Pattern: `[domain]-[descriptive-name].md`
+- Case: lowercase with hyphens
+- Example: `pr-review-security.md`, `pester-test-isolation.md`
+
+**Entity IDs** (inside file content):
+
+- Pattern: `[Type]-[Name]` or `Skill-[Category]-[NNN]`
+- Case: PascalCase with hyphen separator
+- Example: `Skill-PR-001`, `Feature-Authentication`
+
+| Type | Entity ID Pattern | File Name Pattern |
+|------|-------------------|-------------------|
+| Skill | `Skill-[Category]-[NNN]` | `[domain]-[topic].md` |
+| Feature | `Feature-[Name]` | `feature-[name].md` |
+| Decision | `ADR-[Number]` | `adr-[number]-[topic].md` |
+| Pattern | `Pattern-[Name]` | `pattern-[name].md` |
+
+## Relations (Encoded in File Content)
+
+Relations are encoded as markdown in the memory file:
+
+```markdown
+## Relations
+
+- **supersedes**: [previous-file-name]
+- **depends_on**: [dependency-file-name]
+- **related_to**: [related-file-name]
+```
+
+| Relation | Use When | Example |
+|----------|----------|---------|
+| `supersedes` | New version replaces old | `supersedes: adr-003-old-auth` |
+| `depends_on` | Requires another memory | `depends_on: session-init-serena` |
+| `related_to` | Loose association | `related_to: pr-review-security` |
+| `blocks` | This memory blocks another | `blocks: implementation-start` |
+| `enables` | This memory enables another | `enables: skill-validation` |
 
 ## Retrieval Protocol
 
@@ -190,19 +206,60 @@ memory_file_name: "powershell-testing-patterns"
 - Every 5 turns of extended work
 - Session end
 
-**Creating New Memories:**
+### Create vs Update Decision
+
+```mermaid
+flowchart TD
+    START([New Learning]) --> Q1{Existing memory<br/>covers this topic?}
+    Q1 -->|YES| UPDATE[Update existing<br/>with edit_memory]
+    Q1 -->|NO| Q2{Related domain<br/>index exists?}
+    Q2 -->|YES| CREATE[Create new file<br/>Add to domain index]
+    Q2 -->|NO| Q3{5+ memories<br/>expected for topic?}
+    Q3 -->|YES| NEWDOMAIN[Create new domain<br/>index + memory file]
+    Q3 -->|NO| RELATED[Add to closest<br/>related domain]
+```
+
+**Update existing** when: Adding observation, refining pattern, source-tracked timeline entry.
+**Create new** when: Distinct atomic unit, new capability, no existing coverage.
+
+### Domain Selection
+
+Consult `memory-index.md` to find correct domain:
+
+```text
+mcp__serena__read_memory
+memory_file_name: "memory-index"
+```
+
+Match memory topic against Task Keywords column to find domain index.
+
+| Memory Topic | Domain Index | File Name Pattern |
+|--------------|--------------|-------------------|
+| PowerShell patterns | skills-powershell-index | `powershell-[topic].md` |
+| GitHub CLI usage | skills-github-cli-index | `github-cli-[topic].md` |
+| PR review workflows | skills-pr-review-index | `pr-review-[topic].md` |
+| Testing patterns | skills-pester-testing-index | `pester-[topic].md` |
+| Documentation | skills-documentation-index | `documentation-[topic].md` |
+| Session init | skills-session-init-index | `session-init-[topic].md` |
+
+### Creating New Memories
 
 ```text
 # Step 1: Create atomic memory file
 mcp__serena__write_memory
 memory_file_name: "[domain]-[descriptive-name]"
 content: "# [Title]\n\n**Statement**: [Atomic description]\n\n**Context**: [When applicable]\n\n**Evidence**: [Source/proof]\n\n## Details\n\n[Content]"
 
-# Step 2: Update domain index with new entry
+# 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
 mcp__serena__edit_memory
 memory_file_name: "skills-[domain]-index"
-needle: "| Keywords | File |"
-repl: "| Keywords | File |\n|----------|------|\n| [keywords] | [new-file-name] |"
+needle: "| [last-existing-keywords] | [last-existing-file] |"
+repl: "| [last-existing-keywords] | [last-existing-file] |\n| [new-keywords] | [new-file-name] |"
 mode: "literal"
 ```
 

src/claude/skillbook.md

@@ -261,6 +261,7 @@ flowchart TD
 ```
 
 **CRITICAL/BLOCKING Definition** (any one triggers Format A):
+
 - Impact score >= 9
 - Blocks a protocol gate (SESSION-PROTOCOL.md)
 - Tagged with `#P0` or `#BLOCKING`
@@ -291,6 +292,7 @@ flowchart TD
 3. **Fallback to related**: If <5 skills expected, add to closest related domain.
 
 **Example decisions:**
+
 - Skill about PR security → `skills-pr-review-index.md` (PR workflow context)
 - Skill about skill formatting → `skills-documentation-index.md` (documentation context)
 - Skill about Pester mocking → `skills-pester-testing-index.md` (testing context)
@@ -320,6 +322,7 @@ memory_file_name: "memory-index"
 Match skill keywords against the Task Keywords column. The Essential Memories column shows which index to use.
 
 **Creating new domains**: Only create `skills-{domain}-index.md` when:
+
 1. 5+ skills exist or are planned for the topic
 2. No existing domain covers the topic adequately
 3. Keywords are distinct from all existing domains
@@ -355,6 +358,7 @@ grep -r "Skill-PR-" .serena/memories/ | grep -oE "Skill-PR-[0-9]+" | sort -t'-'
 ```
 
 **Rules:**
+
 - Numbers are sequential within category (001, 002, 003...)
 - Do NOT reuse numbers from deleted skills
 - Gaps are acceptable (001, 002, 005 if 003-004 were deleted)

src/copilot-cli/memory.agent.md

@@ -152,19 +152,60 @@ memory_file_name: "powershell-testing-patterns"
 - Every 5 turns of extended work
 - Session end
 
-**Creating New Memories:**
+### Create vs Update Decision
+
+```mermaid
+flowchart TD
+    START([New Learning]) --> Q1{Existing memory<br/>covers this topic?}
+    Q1 -->|YES| UPDATE[Update existing<br/>with edit_memory]
+    Q1 -->|NO| Q2{Related domain<br/>index exists?}
+    Q2 -->|YES| CREATE[Create new file<br/>Add to domain index]
+    Q2 -->|NO| Q3{5+ memories<br/>expected for topic?}
+    Q3 -->|YES| NEWDOMAIN[Create new domain<br/>index + memory file]
+    Q3 -->|NO| RELATED[Add to closest<br/>related domain]
+```
+
+**Update existing** when: Adding observation, refining pattern, source-tracked timeline entry.
+**Create new** when: Distinct atomic unit, new capability, no existing coverage.
+
+### Domain Selection
+
+Consult `memory-index.md` to find correct domain:
+
+```text
+serena/read_memory
+memory_file_name: "memory-index"
+```
+
+Match memory topic against Task Keywords column to find domain index.
+
+| Memory Topic | Domain Index | File Name Pattern |
+|--------------|--------------|-------------------|
+| PowerShell patterns | skills-powershell-index | `powershell-[topic].md` |
+| GitHub CLI usage | skills-github-cli-index | `github-cli-[topic].md` |
+| PR review workflows | skills-pr-review-index | `pr-review-[topic].md` |
+| Testing patterns | skills-pester-testing-index | `pester-[topic].md` |
+| Documentation | skills-documentation-index | `documentation-[topic].md` |
+| Session init | skills-session-init-index | `session-init-[topic].md` |
+
+### Creating New Memories
 
 ```text
 # Step 1: Create atomic memory file
 serena/write_memory
 memory_file_name: "[domain]-[descriptive-name]"
 content: "# [Title]\n\n**Statement**: [Atomic description]\n\n**Context**: [When applicable]\n\n**Evidence**: [Source/proof]\n\n## Details\n\n[Content]"
 
-# Step 2: Update domain index with new entry
+# 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
 serena/edit_memory
 memory_file_name: "skills-[domain]-index"
-needle: "| Keywords | File |"
-repl: "| Keywords | File |\n|----------|------|\n| [keywords] | [new-file-name] |"
+needle: "| [last-existing-keywords] | [last-existing-file] |"
+repl: "| [last-existing-keywords] | [last-existing-file] |\n| [new-keywords] | [new-file-name] |"
 mode: "literal"
 ```
 
@@ -186,27 +227,46 @@ After creating memories, run validation:
 pwsh scripts/Validate-MemoryIndex.ps1
 ```
 
-## Entity Naming Conventions
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| Feature | Feature-[Name] | Feature-Authentication |
-| Module | Module-[Name] | Module-Identity |
-| Decision | ADR-[Number] | ADR-001 |
-| Pattern | Pattern-[Name] | Pattern-StrategyTax |
-| Problem | Problem-[Name] | Problem-CachingRace |
-| Solution | Solution-[Name] | Solution-LockingCache |
-
-## Relation Types
-
-| Relation | Meaning |
-|----------|---------|
-| implemented_in | Feature is implemented in Module |
-| depends_on | Entity requires another |
-| replaces | New approach replaces old |
-| related_to | General association |
-| blocked_by | Progress blocked by issue |
-| solved_by | Problem has solution |
+## File Naming vs Entity IDs
+
+**File Names** (Serena storage):
+
+- Pattern: `[domain]-[descriptive-name].md`
+- Case: lowercase with hyphens
+- Example: `pr-review-security.md`, `pester-test-isolation.md`
+
+**Entity IDs** (inside file content):
+
+- Pattern: `[Type]-[Name]` or `Skill-[Category]-[NNN]`
+- Case: PascalCase with hyphen separator
+- Example: `Skill-PR-001`, `Feature-Authentication`
+
+| Type | Entity ID Pattern | File Name Pattern |
+|------|-------------------|-------------------|
+| Skill | `Skill-[Category]-[NNN]` | `[domain]-[topic].md` |
+| Feature | `Feature-[Name]` | `feature-[name].md` |
+| Decision | `ADR-[Number]` | `adr-[number]-[topic].md` |
+| Pattern | `Pattern-[Name]` | `pattern-[name].md` |
+
+## Relations (Encoded in File Content)
+
+Relations are encoded as markdown in the memory file:
+
+```markdown
+## Relations
+
+- **supersedes**: [previous-file-name]
+- **depends_on**: [dependency-file-name]
+- **related_to**: [related-file-name]
+```
+
+| Relation | Use When | Example |
+|----------|----------|---------|
+| `supersedes` | New version replaces old | `supersedes: adr-003-old-auth` |
+| `depends_on` | Requires another memory | `depends_on: session-init-serena` |
+| `related_to` | Loose association | `related_to: pr-review-security` |
+| `blocks` | This memory blocks another | `blocks: implementation-start` |
+| `enables` | This memory enables another | `enables: skill-validation` |
 
 ## Conflict Resolution
 

src/copilot-cli/skillbook.agent.md

@@ -223,6 +223,7 @@ flowchart TD
 ```
 
 **CRITICAL/BLOCKING Definition** (any one triggers Format A):
+
 - Impact score >= 9
 - Blocks a protocol gate (SESSION-PROTOCOL.md)
 - Tagged with `#P0` or `#BLOCKING`
@@ -253,6 +254,7 @@ flowchart TD
 3. **Fallback to related**: If <5 skills expected, add to closest related domain.
 
 **Example decisions:**
+
 - Skill about PR security → `skills-pr-review-index.md` (PR workflow context)
 - Skill about skill formatting → `skills-documentation-index.md` (documentation context)
 - Skill about Pester mocking → `skills-pester-testing-index.md` (testing context)
@@ -282,6 +284,7 @@ memory_file_name: "memory-index"
 Match skill keywords against the Task Keywords column. The Essential Memories column shows which index to use.
 
 **Creating new domains**: Only create `skills-{domain}-index.md` when:
+
 1. 5+ skills exist or are planned for the topic
 2. No existing domain covers the topic adequately
 3. Keywords are distinct from all existing domains
@@ -317,6 +320,7 @@ grep -r "Skill-PR-" .serena/memories/ | grep -oE "Skill-PR-[0-9]+" | sort -t'-'
 ```
 
 **Rules:**
+
 - Numbers are sequential within category (001, 002, 003...)
 - Do NOT reuse numbers from deleted skills
 - Gaps are acceptable (001, 002, 005 if 003-004 were deleted)