session-intelligence-harvester

Session Intelligence Harvester

Overview

Transform session learnings into permanent organizational intelligence by implementing updates across RII components. After productive sessions involving corrections, discoveries, or pattern identification, systematically extract what was learned, route it to the correct component, and apply the changes.

Why this matters: One-time fixes that aren't encoded into RII components will recur. The Chapter N skill format drift happened because no check existed to prevent it. After harvesting, that failure mode is encoded in 4 files—future sessions automatically benefit.

When to Use This Skill

Automatic Triggers (proactively suggest harvesting):

• Session corrected format drift (wrong file structure, YAML, invocation)
• Session added missing checks to orchestration files
• Session identified failure mode worth preventing
• Session touched 3+ files with similar pattern corrections
• PHR was created documenting significant learning

Manual Triggers (user requests):

• "Harvest learnings from this session"
• "Capture session intelligence"
• "What should we encode from this work?"
• "Update RII with what we learned"

Workflow

Default to action: Implement all updates rather than only proposing them. Read target files, make edits, and commit changes. Only propose without implementing if explicitly asked.

Step 1: Session Analysis

Analyze the session by answering these questions. Write your analysis to track progress:

1. CORRECTIONS MADE
   - What errors/drift were corrected?
   - What was wrong vs what is now correct?
   - Why did the error occur? (missing check, format drift, etc.)

   WHY THIS MATTERS: Understanding root cause determines which RII
   component prevents recurrence. Format drift → agent convergence
   pattern. Missing context → CLAUDE.md protocol step.

2. PATTERNS IDENTIFIED
   - What recurring patterns emerged?
   - What canonical sources were referenced?
   - What validation would have caught this earlier?

   WHY THIS MATTERS: Patterns that recur across sessions deserve
   encoding. If you referenced a canonical source, other sessions
   will need that same reference.

3. LEARNING CLASSIFICATION
   - Context-gathering gap? (CLAUDE.md)
   - Pedagogical/teaching issue? (Constitution)
   - Agent convergence pattern? (Agents)
   - Reusable workflow? (Skills)
   - Missing orchestration check? (Commands)

   WHY THIS MATTERS: Wrong routing means learnings don't trigger at
   the right time. A convergence pattern in CLAUDE.md won't help
   chapter-planner catch it during planning.

Step 2: Route to RII Components

Use this routing table. Route learnings to the component where they will be discovered at the right time:

Learning Type	Target Component	Location	What to Add	When It Triggers
Context-gathering gaps	CLAUDE.md	Section I	New step in context protocol	Before ANY platform work
Failure mode example	CLAUDE.md	Failure modes	Named example with correction	When similar situation detected
Pedagogical framework	Constitution	Section IIa	Teaching method update	During lesson design
Agent convergence pattern	Agent file	Convergence Patterns	Pattern + why + correction	During agent execution
Agent self-monitoring	Agent file	Self-Monitoring Checklist	New checklist item	Before agent finalizes output
Canonical source lookup	Multiple agents	Analysis Questions	Cross-reference check	During planning phase
Reusable workflow	New skill	.claude/skills/	New SKILL.md	When user invokes skill
Orchestration check	Command file	Phase 0 or relevant phase	New validation step	During workflow execution
Format specification	Canonical source chapter	Lesson content	Authoritative format	When teaching that pattern

WHY ROUTING MATTERS: Learnings placed in the wrong component don't prevent recurrence. A check in content-implementer.md won't help if the error happens during chapter-planner execution.

Step 3: Read Target Files and Generate Updates

For each identified learning:

1. Read the target file to understand current structure and find exact placement
2. Generate the update with surrounding context for precise placement
3. Track progress as you work through multiple files

## Learning: [Brief Title]

**Type**: [Context gap | Failure mode | Convergence pattern | etc.]

**Target**: [File path]

**Current State** (after reading file):
[What's missing or incorrect - quote existing content if helpful]

**Exact Placement**:
[Which section, after which content - be specific enough to Edit]

**Content to Add**:
[Exact content, matching the file's style and format]

**Rationale**:
[Why this prevents recurrence - what will trigger this check]

**Canonical Source** (if applicable):
[Which chapter/lesson defines the authoritative format]

Step 4: Implement Updates

Take action: Edit each target file. Use the Edit tool to make changes.

For each update:

1. Read the target file (if not already read)
2. Locate the exact insertion point
3. Apply the edit using Edit tool
4. Verify the edit was applied correctly

Track completion:

Updates Progress:
- [x] CLAUDE.md - Added failure mode section
- [x] chapter-planner.md - Added convergence pattern 6
- [x] sp.loopflow.v2.md - Removed (deprecated, replaced by native Plan Mode)
- [ ] content-implementer.md - Pending

Step 5: Validation

Before finalizing, verify each of these (check the box as you confirm):

- [ ] Read each target file before editing (no speculation about structure)
- [ ] Verified each learning routes to the component where it triggers at the right time
- [ ] Confirmed updates include exact placement context (not vague locations)
- [ ] Checked canonical sources exist for format-related learnings
- [ ] Searched target files to confirm no duplicate information exists
- [ ] Used imperative form for agent files, appropriate style for others
- [ ] Added cross-references where pattern appears in multiple files
- [ ] All edits applied successfully (no pending changes)

Step 6: Create PHR and Commit

1. Create PHR documenting:

   • What was learned
   • Where it was encoded (list all files)
   • Why this improves future work

2. Commit changes with descriptive message:

   feat(intelligence): Harvest session learnings into RII
   
   Updates:
   - [File 1]: [What was added]
   - [File 2]: [What was added]
   
   Prevents: [What failure mode this prevents]
   

RII Component Reference

CLAUDE.md Structure

Section I: Context Gathering Protocol
  - Step 1-N: Sequential context steps
  - Each step has WHAT to do and WHY it matters
  - "Find canonical source" step for pattern teaching

Failure Modes (between Section I and II):
  - Named failure examples: "FAILURE MODE: [Name] Example"
  - "What I did wrong" list
  - "What I should have done" numbered steps
  - "Result" showing what was prevented

Agent File Structure

Analysis Questions (Section III):
  - Numbered questions with "Why this matters" explanation
  - Self-check prompt at end

Principles (Section IV):
  - Named principles with Framework + What this means + Application guidance
  - Self-check prompt

Convergence Patterns (Section VI):
  - "Generic pattern" description
  - "Why this is convergence" explanation
  - "Correction" with specific steps

Self-Monitoring Checklist (Section VIII):
  - Numbered checklist with checkmark emoji prefix
  - Each item is a verification question

Command File Structure

Phase 0: Foundation checks
  - Constitutional reading
  - Canonical source checks (for educational content)
  - Each step explains WHY

Convergence Patterns:
  - Symptom description
  - Detection method
  - Correction steps

Output Format

After completing harvest, provide summary:

## Session Intelligence Harvest Summary

**Session**: [Brief description]
**Date**: [ISO date]
**Status**: COMPLETE

### Learnings Extracted: [N]

| #   | Learning | Type   | Target | Status  |
| --- | -------- | ------ | ------ | ------- |
| 1   | [Title]  | [Type] | [File] | Applied |
| 2   | [Title]  | [Type] | [File] | Applied |

### Updates Applied

1. **[File]**: [What was added] (lines X-Y)
2. **[File]**: [What was added] (lines X-Y)

### PHR Created

- Path: [PHR path]
- Stage: [Stage]

### Canonical Sources Referenced

- [Pattern]: [Chapter X Lesson Y]

### Commit

- Hash: [commit hash]
- Message: [commit message summary]

Examples

Example 1: Format Drift Correction (Multi-File)

Session: Fixed skill format to use domain-based structure

Analysis:

CORRECTIONS MADE:
- Wrong: .claude/skills/section-writer.md (flat file, no domain)
- Correct: .claude/skills/authoring/section-writer/SKILL.md (domain + directory structure)
- Root cause: No domain organization for skills/agents

PATTERNS IDENTIFIED:
- Skills must be in authoring/ or engineering/ domain folders
- Agents must be in authoring/ or engineering/ domain folders
- Multiple files referenced old flat structure

CLASSIFICATION:
- Failure mode → CLAUDE.md
- Convergence pattern → chapter-planner.md, content-implementer.md
- Skill structure → skill-creator, session-intelligence-harvester

Updates Applied:

1. CLAUDE.md: Updated agent architecture section
2. skill-creator: Added domain organization requirement
3. session-intelligence-harvester: Updated routing table with domain paths
4. Moved all skills to authoring/ or engineering/
5. Moved all agents to authoring/ or engineering/
6. Generals Skills are at .claude/skills/

Example 2: Missing Validation (Single File)

Session: Discovered lessons weren't checking chapter-index.md for prerequisites

Analysis:

CORRECTIONS MADE:
- Wrong: Started chapter work without reading chapter-index.md
- Correct: MUST read chapter-index.md first to get Part, proficiency, prerequisites
- Root cause: No mandatory step in context protocol

CLASSIFICATION:
- Context-gathering gap → CLAUDE.md Section I

Updates Applied:

1. CLAUDE.md: Added Step 1 to read chapter-index.md with specific extraction requirements

Example 3: Hallucinated Facts (Chapter 2 Incident)

Session: Wrote 6 lessons with unverified statistics, dates, and adoption numbers

Analysis:

CORRECTIONS MADE:
- Wrong: "50-75% time savings" for goose
- Correct: "75% of engineers save 8-10+ hours/week" (verified via Block announcement)

- Wrong: Conflated Agent Skills timeline (said single date)
- Correct: Oct 16, 2025 = Claude Code launch; Dec 18, 2025 = open standard release

- Wrong: Generic agent support lists
- Correct: Verified lists from official AAIF announcement

- Root cause: Trusted plausible-sounding data from memory instead of web verification

PATTERNS IDENTIFIED:
- Statistics, dates, and quotes MUST be web-verified before publication
- Existing factual-verifier agent was available but not used
- 50% of session time was spent fixing hallucinated facts

CLASSIFICATION:
- Critical failure mode → CLAUDE.md Failure Prevention + new section
- Process gap → Missing mandatory fact-check step

Updates Applied:

1. CLAUDE.md: Added "Content Fact-Checking (MANDATORY)" section
2. CLAUDE.md: Added failure mode example to Failure Prevention list
3. Documented factual-verifier agent invocation pattern

Self-Monitoring

Before marking harvest complete, verify you have:

• Analyzed session to identify all corrections and patterns
• Classified each learning to determine correct routing
• Read each target file before editing (no speculation)
• Applied all edits using Edit tool (not just proposed)
• Verified edits match target file's style and structure
• Added cross-references where patterns appear in multiple files
• Created PHR documenting the harvest
• Committed changes with descriptive message
• Generated summary showing all updates applied