Implement passive context compression recommendations from Vercel research

[rjmurillo-bot]

Context

Vercel research (Jan 2026) demonstrates that compressed passive context in AGENTS.md achieves 100% pass rate vs 79% for skills. Key finding: 40KB → 8KB (80% reduction) with 100% pass rate maintained.

Research: .agents/analysis/vercel-passive-context-vs-skills-research.md
Memory: passive-context-vs-skills-vercel-research

Recommendations

High Priority

1. Compress CRITICAL-CONTEXT.md: Apply pipe-delimited format to reduce token usage

   • Current: Table-based format
   • Target: Pipe-delimited index format
   • Expected reduction: ~60-80%

2. Document Skill vs Passive Decision Framework

   • Add section to SKILL-QUICK-REF.md
   • Criteria: Knowledge → passive context, Actions → skills

3. Optimize memory-index format

   • Convert from table to compressed pipe-delimited
   • Maintain discoverability

Medium Priority

4. Build eval suite for protocol compliance

   • Target behaviors outside model training data
   • Behavior-based assertions (not implementation details)
   • Session protocol compliance verification

5. Skill pruning analysis

   • Identify knowledge-heavy skills → convert to passive context
   • Keep action-heavy skills

Low Priority

6. Automatic context compression tool
   • Utility to compress markdown docs to minimal tokens
   • Apply to @imported files

Compression Format Example

[Session Protocol]
|Phase 1 (BLOCKING): Serena init (activate + initial_instructions)
|Phase 2: Read HANDOFF.md (read-only dashboard)
|Phase 3: Create session log (.agents/sessions/YYYY-MM-DD-session-NN.json)
|Phase 4: Read usage-mandatory memory
|Phase 5: Verify branch (git branch --show-current)

Acceptance Criteria

• CRITICAL-CONTEXT.md compressed with pipe-delimited format
• Token reduction measured (before/after)
• Pass rate validation (protocol compliance tests pass)
• Decision framework documented in SKILL-QUICK-REF.md
• memory-index converted to compressed format

References

• Vercel blog: https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
• Forgetful memories: IDs 495-502
• Related: claude-md-anthropic-best-practices, memory-token-efficiency

[traycerai]

Plan

Observations

The codebase already implements Vercel's passive context strategy with AGENTS.md achieving 100% pass rate. However, key files (CRITICAL-CONTEXT.md, memory-index.md) still use verbose table formats. The research document referenced in the ticket doesn't exist yet - the findings are scattered across AGENTS.md and SKILL-QUICK-REF.md. The compression format example in the ticket shows the target pipe-delimited style already partially implemented in SKILL-QUICK-REF.md (lines 14-18, 28-38, 46-51).

Approach

Apply Vercel's proven compression technique systematically across passive context files. Start with high-impact, low-risk changes (format conversion) before tackling evaluation infrastructure. Prioritize token reduction in auto-loaded files (CRITICAL-CONTEXT.md, memory-index.md) since they're imported via @import in CLAUDE.md. Document the decision framework to prevent future skill/passive context confusion. Defer eval suite and automation tools to later phases as they require more infrastructure investment.

Implementation Steps

High Priority Tasks

1. Create Vercel Research Analysis Document

Create file:.agents/analysis/vercel-passive-context-vs-skills-research.md to consolidate scattered research findings:

• Extract Vercel research data from file:AGENTS.md (lines 1703-1822)
• Extract pass rate table from file:SKILL-QUICK-REF.md (lines 154-164)
• Document the 40KB → 8KB compression achievement
• Include skill classification framework (Horizontal vs Vertical vs Hybrid)
• Add compression format examples with before/after token counts
• Reference the Vercel blog post: https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
• Create corresponding Serena memory with memory_file_name="passive-context-vs-skills-vercel-research"

2. Compress CRITICAL-CONTEXT.md

Convert table-based sections to pipe-delimited format following the pattern in file:SKILL-QUICK-REF.md:

Section: Blocking Constraints (lines 8-16)

• Current: 7-row table with columns (Constraint, Rationale, Verification)
• Target: Pipe-delimited list format
• Example transformation:

  [Blocking Constraints]
  |Python-first (.py preferred): ADR-042 AI/ML alignment → verify new scripts
  |No raw gh when skill exists: Skills tested/validated → check .claude/skills/github/
  |No logic in workflow YAML: ADR-006 testability → delegate to PowerShell
  |Verify branch before git ops: SESSION-PROTOCOL prevent wrong-branch → git branch --show-current
  |HANDOFF.md read-only: ADR-014 distributed handoff → never edit
  |ADR created/edited → adr-review: Multi-agent consensus → run adr-review skill
  |Local workflow test before push: Shift-left catch errors → gh act on changed workflows
  

Section: Session Protocol Gates (lines 20-37)

• Convert numbered lists to pipe-delimited phases
• Follow the compression example from the ticket

Section: Skill-First Pattern (lines 63-72)

• Convert operation table to compressed mapping format
• Maintain the positive checkpoint framing

Section: PR Review Comment Routing (lines 79-100)

• Compress routing tables to pattern detection format

Measure token reduction: Run token counter on original vs compressed versions, document in commit message.

3. Optimize memory-index.md Format

Convert file:.serena/memories/memory-index.md from table format to compressed pipe-delimited:

Current format (lines 3-56): Table with columns (Task Keywords | Essential Memories)

Target format:

[Memory Index]
|session start init handoff protocol serena blocking → skills-session-init-index, project-overview, codebase-structure
|session validation diagnose fixer protocol compliance → changelog-session-log-fixer
|github pr issue cli gh api review comment batch → skills-github-cli-index, skills-pr-review-index, pr-review-batch-response-pattern, project-labels-milestones
|graphql mutation query resolve thread reply batch → skills-graphql-index
|jq json parse filter select map array object → skills-jq-index
...

Engineering Knowledge Tiers section (lines 58-65): Convert to pipe-delimited format

User Constraints section (lines 67-72): Convert to pipe-delimited format

Maintain discoverability by keeping keywords at the start of each line for easy scanning.

4. Document Skill vs Passive Decision Framework

Add new section to file:SKILL-QUICK-REF.md after line 165 (after "Why Passive Context" section):

Section title: "Skill vs Passive Context Decision Framework"

Content structure:

• Decision criteria table: Knowledge → passive context, Actions → skills
• Classification flowchart using Mermaid diagram
• Examples of each category (Horizontal, Vertical, Hybrid)
• Migration checklist for converting skills to passive context
• Token budget guidelines (target: 10KB ceiling for auto-loaded context)

Reference the classification framework from file:AGENTS.md (lines 1730-1766) and compress it to pipe-delimited format.

Medium Priority Tasks

5. Build Eval Suite for Protocol Compliance

Create file:.agents/testing/protocol-compliance-eval-suite.md specification:

Target behaviors (outside model training data):

• Session protocol phase completion verification
• Branch verification before git operations
• Skill-first checkpoint adherence
• Memory-first retrieval pattern
• QA validation gate enforcement

Assertion structure (behavior-based, not implementation):

• Input: Session transcript or session log JSON
• Expected: Protocol compliance checklist completion
• Verification: Parse session log, check required fields exist and are non-empty

Session protocol compliance tests:

• Test 1: Serena initialization occurs before file reads
• Test 2: HANDOFF.md read before work starts
• Test 3: Session log created within first 5 tool calls
• Test 4: Branch verification documented in session log
• Test 5: QA validation ran for feature sessions (or skip evidence documented)

Reference existing validation script file:scripts/Validate-SessionJson.ps1 for structural validation patterns.

Create corresponding test implementation in file:.agents/testing/test_protocol_compliance.py using pytest framework (per ADR-042 Python-first strategy).

6. Skill Pruning Analysis

Create file:.agents/analysis/skill-pruning-candidates.md:

Analysis criteria:

• Identify skills with >70% knowledge content vs action content
• Measure skill invocation frequency from session logs
• Calculate token cost of skill vs passive context equivalent
• Assess conversion feasibility (breaking changes, dependencies)

Candidate identification process:

• Scan file:.claude/skills/ directory for all SKILL.md files
• Classify each skill using Horizontal/Vertical/Hybrid framework
• For Horizontal candidates: Extract knowledge sections, estimate token reduction
• For Hybrid candidates: Identify split points between knowledge and actions

Output: Prioritized list of skills to convert, with estimated token savings and migration effort.

Reference the skill classification from file:AGENTS.md (lines 1738-1766) for initial candidates.

Low Priority Tasks

7. Automatic Context Compression Tool

Create file:.agents/tools/compress-passive-context.py:

Functionality:

• Input: Markdown file path
• Output: Compressed pipe-delimited format
• Compression rules:
  • Tables → pipe-delimited lists
  • Numbered lists → pipe-delimited phases
  • Verbose descriptions → compressed key:value pairs
  • Preserve semantic meaning while reducing tokens

Algorithm:

• Parse markdown AST (use markdown-it-py library)
• Detect table structures, extract columns
• Transform to |column1: value1 → column2: value2 format
• Measure token reduction (before/after)
• Validate compressed output maintains discoverability

Usage:

uv run python .agents/tools/compress-passive-context.py --input CRITICAL-CONTEXT.md --output CRITICAL-CONTEXT-compressed.md --measure-tokens

Apply to @imported files in file:CLAUDE.md to optimize auto-loaded context.

Validation & Measurement

Token Reduction Measurement

For each compressed file:

1. Count tokens before compression (use tiktoken library with cl100k_base encoding)
2. Count tokens after compression
3. Calculate reduction percentage
4. Document in commit message: docs: compress CRITICAL-CONTEXT.md (2.5KB → 1.2KB, 52% reduction)

Pass Rate Validation

After compression changes:

1. Run existing protocol compliance tests: pwsh scripts/Validate-SessionJson.ps1 on recent session logs
2. Verify no regressions in session protocol adherence
3. Check that compressed context maintains discoverability (manual review)
4. Confirm auto-loaded files still parse correctly in CLAUDE.md @import statements

Acceptance Criteria Checklist

• CRITICAL-CONTEXT.md compressed with pipe-delimited format
• Token reduction measured and documented (target: 60-80% reduction)
• Pass rate validation completed (protocol compliance tests pass)
• Decision framework documented in SKILL-QUICK-REF.md
• memory-index.md converted to compressed format
• Vercel research analysis document created at .agents/analysis/vercel-passive-context-vs-skills-research.md
• Serena memory created with ID passive-context-vs-skills-vercel-research

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Research as Research Doc
    participant Critical as CRITICAL-CONTEXT.md
    participant Memory as memory-index.md
    participant SkillRef as SKILL-QUICK-REF.md
    participant Validation as Validation Suite

    Dev->>Research: 1. Create Vercel research analysis
    Research-->>Dev: Document created with findings
    
    Dev->>Critical: 2. Compress tables to pipe-delimited
    Critical-->>Dev: Token count: before/after
    
    Dev->>Memory: 3. Compress memory index
    Memory-->>Dev: Token count: before/after
    
    Dev->>SkillRef: 4. Add decision framework section
    SkillRef-->>Dev: Framework documented
    
    Dev->>Validation: 5. Run protocol compliance tests
    Validation-->>Dev: Pass rate: 100% maintained
    
    Note over Dev,Validation: Medium Priority (Optional)
    Dev->>Validation: 6. Build eval suite
    Dev->>Research: 7. Skill pruning analysis
    
    Note over Dev,Validation: Low Priority (Future)
    Dev->>Dev: 8. Create compression tool

Loading

Related Files

• file:CRITICAL-CONTEXT.md - Primary compression target
• file:SKILL-QUICK-REF.md - Decision framework location, compression pattern reference
• file:.serena/memories/memory-index.md - Memory index compression target
• file:AGENTS.md - Source of Vercel research data (lines 1703-1822)
• file:CLAUDE.md - Entry point with @import statements for auto-loaded context
• file:.agents/SESSION-PROTOCOL.md - Protocol requirements for eval suite
• file:scripts/Validate-SessionJson.ps1 - Existing validation pattern reference

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase already implements Vercel's passive context strategy with AGENTS.md achieving 100% pass rate. However, key files (CRITICAL-CONTEXT.md, memory-index.md) still use verbose table formats. The research document referenced in the ticket doesn't exist yet - the findings are scattered across AGENTS.md and SKILL-QUICK-REF.md. The compression format example in the ticket shows the target pipe-delimited style already partially implemented in SKILL-QUICK-REF.md (lines 14-18, 28-38, 46-51).

## Approach

Apply Vercel's proven compression technique systematically across passive context files. Start with high-impact, low-risk changes (format conversion) before tackling evaluation infrastructure. Prioritize token reduction in auto-loaded files (CRITICAL-CONTEXT.md, memory-index.md) since they're imported via `@import` in CLAUDE.md. Document the decision framework to prevent future skill/passive context confusion. Defer eval suite and automation tools to later phases as they require more infrastructure investment.

## Implementation Steps

### High Priority Tasks

#### 1. Create Vercel Research Analysis Document

Create `file:.agents/analysis/vercel-passive-context-vs-skills-research.md` to consolidate scattered research findings:

- Extract Vercel research data from `file:AGENTS.md` (lines 1703-1822)
- Extract pass rate table from `file:SKILL-QUICK-REF.md` (lines 154-164)
- Document the 40KB → 8KB compression achievement
- Include skill classification framework (Horizontal vs Vertical vs Hybrid)
- Add compression format examples with before/after token counts
- Reference the Vercel blog post: https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
- Create corresponding Serena memory with `memory_file_name="passive-context-vs-skills-vercel-research"`

#### 2. Compress CRITICAL-CONTEXT.md

Convert table-based sections to pipe-delimited format following the pattern in `file:SKILL-QUICK-REF.md`:

**Section: Blocking Constraints (lines 8-16)**
- Current: 7-row table with columns (Constraint, Rationale, Verification)
- Target: Pipe-delimited list format
- Example transformation:
  ```text
  [Blocking Constraints]
  |Python-first (.py preferred): ADR-042 AI/ML alignment → verify new scripts
  |No raw gh when skill exists: Skills tested/validated → check .claude/skills/github/
  |No logic in workflow YAML: ADR-006 testability → delegate to PowerShell
  |Verify branch before git ops: SESSION-PROTOCOL prevent wrong-branch → git branch --show-current
  |HANDOFF.md read-only: ADR-014 distributed handoff → never edit
  |ADR created/edited → adr-review: Multi-agent consensus → run adr-review skill
  |Local workflow test before push: Shift-left catch errors → gh act on changed workflows
  ```

**Section: Session Protocol Gates (lines 20-37)**
- Convert numbered lists to pipe-delimited phases
- Follow the compression example from the ticket

**Section: Skill-First Pattern (lines 63-72)**
- Convert operation table to compressed mapping format
- Maintain the positive checkpoint framing

**Section: PR Review Comment Routing (lines 79-100)**
- Compress routing tables to pattern detection format

Measure token reduction: Run token counter on original vs compressed versions, document in commit message.

#### 3. Optimize memory-index.md Format

Convert `file:.serena/memories/memory-index.md` from table format to compressed pipe-delimited:

**Current format (lines 3-56)**: Table with columns (Task Keywords | Essential Memories)

**Target format**:
```text
[Memory Index]
|session start init handoff protocol serena blocking → skills-session-init-index, project-overview, codebase-structure
|session validation diagnose fixer protocol compliance → changelog-session-log-fixer
|github pr issue cli gh api review comment batch → skills-github-cli-index, skills-pr-review-index, pr-review-batch-response-pattern, project-labels-milestones
|graphql mutation query resolve thread reply batch → skills-graphql-index
|jq json parse filter select map array object → skills-jq-index
...
```

**Engineering Knowledge Tiers section (lines 58-65)**: Convert to pipe-delimited format

**User Constraints section (lines 67-72)**: Convert to pipe-delimited format

Maintain discoverability by keeping keywords at the start of each line for easy scanning.

#### 4. Document Skill vs Passive Decision Framework

Add new section to `file:SKILL-QUICK-REF.md` after line 165 (after "Why Passive Context" section):

**Section title**: "Skill vs Passive Context Decision Framework"

**Content structure**:
- Decision criteria table: Knowledge → passive context, Actions → skills
- Classification flowchart using Mermaid diagram
- Examples of each category (Horizontal, Vertical, Hybrid)
- Migration checklist for converting skills to passive context
- Token budget guidelines (target: 10KB ceiling for auto-loaded context)

Reference the classification framework from `file:AGENTS.md` (lines 1730-1766) and compress it to pipe-delimited format.

### Medium Priority Tasks

#### 5. Build Eval Suite for Protocol Compliance

Create `file:.agents/testing/protocol-compliance-eval-suite.md` specification:

**Target behaviors** (outside model training data):
- Session protocol phase completion verification
- Branch verification before git operations
- Skill-first checkpoint adherence
- Memory-first retrieval pattern
- QA validation gate enforcement

**Assertion structure** (behavior-based, not implementation):
- Input: Session transcript or session log JSON
- Expected: Protocol compliance checklist completion
- Verification: Parse session log, check required fields exist and are non-empty

**Session protocol compliance tests**:
- Test 1: Serena initialization occurs before file reads
- Test 2: HANDOFF.md read before work starts
- Test 3: Session log created within first 5 tool calls
- Test 4: Branch verification documented in session log
- Test 5: QA validation ran for feature sessions (or skip evidence documented)

Reference existing validation script `file:scripts/Validate-SessionJson.ps1` for structural validation patterns.

Create corresponding test implementation in `file:.agents/testing/test_protocol_compliance.py` using pytest framework (per ADR-042 Python-first strategy).

#### 6. Skill Pruning Analysis

Create `file:.agents/analysis/skill-pruning-candidates.md`:

**Analysis criteria**:
- Identify skills with >70% knowledge content vs action content
- Measure skill invocation frequency from session logs
- Calculate token cost of skill vs passive context equivalent
- Assess conversion feasibility (breaking changes, dependencies)

**Candidate identification process**:
- Scan `file:.claude/skills/` directory for all SKILL.md files
- Classify each skill using Horizontal/Vertical/Hybrid framework
- For Horizontal candidates: Extract knowledge sections, estimate token reduction
- For Hybrid candidates: Identify split points between knowledge and actions

**Output**: Prioritized list of skills to convert, with estimated token savings and migration effort.

Reference the skill classification from `file:AGENTS.md` (lines 1738-1766) for initial candidates.

### Low Priority Tasks

#### 7. Automatic Context Compression Tool

Create `file:.agents/tools/compress-passive-context.py`:

**Functionality**:
- Input: Markdown file path
- Output: Compressed pipe-delimited format
- Compression rules:
  - Tables → pipe-delimited lists
  - Numbered lists → pipe-delimited phases
  - Verbose descriptions → compressed key:value pairs
  - Preserve semantic meaning while reducing tokens

**Algorithm**:
- Parse markdown AST (use `markdown-it-py` library)
- Detect table structures, extract columns
- Transform to `|column1: value1 → column2: value2` format
- Measure token reduction (before/after)
- Validate compressed output maintains discoverability

**Usage**:
```bash
uv run python .agents/tools/compress-passive-context.py --input CRITICAL-CONTEXT.md --output CRITICAL-CONTEXT-compressed.md --measure-tokens
```

Apply to `@imported` files in `file:CLAUDE.md` to optimize auto-loaded context.

## Validation & Measurement

### Token Reduction Measurement

For each compressed file:
1. Count tokens before compression (use `tiktoken` library with `cl100k_base` encoding)
2. Count tokens after compression
3. Calculate reduction percentage
4. Document in commit message: `docs: compress CRITICAL-CONTEXT.md (2.5KB → 1.2KB, 52% reduction)`

### Pass Rate Validation

After compression changes:
1. Run existing protocol compliance tests: `pwsh scripts/Validate-SessionJson.ps1` on recent session logs
2. Verify no regressions in session protocol adherence
3. Check that compressed context maintains discoverability (manual review)
4. Confirm auto-loaded files still parse correctly in CLAUDE.md `@import` statements

### Acceptance Criteria Checklist

- [ ] CRITICAL-CONTEXT.md compressed with pipe-delimited format
- [ ] Token reduction measured and documented (target: 60-80% reduction)
- [ ] Pass rate validation completed (protocol compliance tests pass)
- [ ] Decision framework documented in SKILL-QUICK-REF.md
- [ ] memory-index.md converted to compressed format
- [ ] Vercel research analysis document created at `.agents/analysis/vercel-passive-context-vs-skills-research.md`
- [ ] Serena memory created with ID `passive-context-vs-skills-vercel-research`

## Sequence Diagram

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant Research as Research Doc
    participant Critical as CRITICAL-CONTEXT.md
    participant Memory as memory-index.md
    participant SkillRef as SKILL-QUICK-REF.md
    participant Validation as Validation Suite

    Dev->>Research: 1. Create Vercel research analysis
    Research-->>Dev: Document created with findings
    
    Dev->>Critical: 2. Compress tables to pipe-delimited
    Critical-->>Dev: Token count: before/after
    
    Dev->>Memory: 3. Compress memory index
    Memory-->>Dev: Token count: before/after
    
    Dev->>SkillRef: 4. Add decision framework section
    SkillRef-->>Dev: Framework documented
    
    Dev->>Validation: 5. Run protocol compliance tests
    Validation-->>Dev: Pass rate: 100% maintained
    
    Note over Dev,Validation: Medium Priority (Optional)
    Dev->>Validation: 6. Build eval suite
    Dev->>Research: 7. Skill pruning analysis
    
    Note over Dev,Validation: Low Priority (Future)
    Dev->>Dev: 8. Create compression tool
```

## Related Files

- `file:CRITICAL-CONTEXT.md` - Primary compression target
- `file:SKILL-QUICK-REF.md` - Decision framework location, compression pattern reference
- `file:.serena/memories/memory-index.md` - Memory index compression target
- `file:AGENTS.md` - Source of Vercel research data (lines 1703-1822)
- `file:CLAUDE.md` - Entry point with `@import` statements for auto-loaded context
- `file:.agents/SESSION-PROTOCOL.md` - Protocol requirements for eval suite
- `file:scripts/Validate-SessionJson.ps1` - Existing validation pattern reference

---

Execution Information

Branch: main
Commit: 14316db

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#245 - docs(memory): add decomposition analysis for Issue #239 [merged]
#255 - feat(github-skill): enhance skill for Claude effectiveness [merged]
#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#752 - feat(memory): memory system foundation (Session 230) [merged]
#775 - docs: implement CLAUDE.md @imports pattern [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[rjmurillo]

Velocity Accelerator: 2 Opportunities Detected

Triage issue #1106: Implement passive context compression recommendations from V

• Type: complexity_triage
• Priority: medium
• Suggested Agent: agent-devops
• Issue labeled with medium complexity.
  Suggested agents: agent-devops, agent-implementer, agent-qa, agent-analyst, agent-explainer

Route issue #1106 to agent-devops, agent-implementer, agent-qa, agent-analyst, agent-explainer

• Type: agent_routing
• Priority: low
• Suggested Agent: agent-devops
• Issue content suggests routing to: agent-devops, agent-implementer, agent-qa, agent-analyst, agent-explainer
  Complexity: medium

[github-actions]

Product Requirements Document

Important

This PRD was automatically generated based on issue triage escalation.
Complexity Score: 6/12 (Standard)
Escalation Criteria: feature_request,multi_phase_work,architectural_impact

About this PRD

This PRD was generated by the Explainer Agent after the issue was flagged
for detailed analysis. The document is designed to be self-contained - it can
be passed to a separate AI agent instance for implementation without additional
context.

PRD Depth Levels:

• Standard (4-6): Brief analysis, clear requirements
• Detailed (7-9): Research section, blocking questions
• Comprehensive (10-12): Phased implementation, risk analysis

---

Now I have enough context to create a comprehensive PRD. Let me create the document.

The file creation was blocked. Let me output the PRD directly since I cannot create the file:

---

PRD: Passive Context Compression (Vercel Research Implementation)

Executive Summary

The Vercel AI team published research (Jan 2026) demonstrating that compressed passive context in AGENTS.md achieves 100% protocol compliance pass rate versus 53-79% for skill-based approaches. This repository already implements @import pattern with CRITICAL-CONTEXT.md and SKILL-QUICK-REF.md. This PRD defines the work to apply Vercel's compression recommendations to maximize token efficiency while maintaining protocol compliance.

Scope	Status	Blocker
Compress CRITICAL-CONTEXT.md to pipe-delimited format	🟢 READY	None
Document Skill vs Passive Decision Framework	🟢 READY	None
Optimize memory-index format	🟢 READY	None
Build eval suite for protocol compliance	🟡 PARTIAL	Requires test infrastructure design
Skill pruning analysis	🟢 READY	None
Automatic compression tool	🟡 PARTIAL	Low priority; manual compression sufficient

Verdict: READY for Phase 1-3. Phase 4-6 require design decisions before implementation.

Problem Statement

Current State

File	Lines	Est. Tokens	Purpose
CLAUDE.md	82	~600	Entry point with @imports
CRITICAL-CONTEXT.md	107	~1,200	Blocking constraints and session protocol
SKILL-QUICK-REF.md	166	~1,800	Skill routing and memory hierarchy
memory-index.md	80	~900	Two-column task-to-memory mapping
Total Auto-loaded	435	~4,500	Every session context

Token budget target: 10KB ceiling per Anthropic guidance. Current: ~4,500 tokens (~8.5KB). Room for optimization.

Gap Analysis

1. Table format inefficiency: CRITICAL-CONTEXT.md uses markdown tables which consume tokens for formatting characters
2. Memory index uses table format: memory-index.md could use compressed index format
3. No decision framework documented: Agents lack criteria for when to use passive context vs skills
4. No validation suite: Protocol compliance is not programmatically testable
5. Knowledge-heavy skills exist: Some skills contain reference material that should be passive context

User Impact

User	Impact
Agent developers	Wasted tokens on formatting overhead
AI agents	47% failure rate on skill invocation (Vercel data)
Repository maintainers	No way to verify compression effectiveness

Research Findings

Primary Source: Vercel Research (Jan 2026)

Source: https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals

Key Findings (CONFIRMED):

Configuration	Pass Rate
Baseline (no docs)	53%
Skill (default behavior)	53%
Skill + explicit instructions	79%
AGENTS.md passive context	100%

Compression Achievement: 40KB to 8KB (80% reduction) with 100% pass rate maintained.

Mechanism: "No decision point required. Information is present every turn."

Secondary Source: Repository Memory (CONFIRMED)

Memory claude-md-anthropic-best-practices documents:

• 100-200 lines maximum for CLAUDE.md
• @imports pattern for recursive loading (max depth 5)
• Anti-pattern: monolithic files

Memory memory-token-efficiency documents:

• Activation vocabulary principle for memory discoverability
• Trade-off: file count vs per-read cost

Compression Format Specification

Vercel's pipe-delimited format replaces verbose tables:

Before (Table):

| Constraint | Rationale | Verification |
|------------|-----------|--------------|
| Python-first (.py preferred) | ADR-042 | New scripts in Python |

After (Pipe-delimited):

[Blocking Constraints]
|Python-first (.py): ADR-042, new scripts in Python
|No raw gh when skill exists: usage-mandatory, check .claude/skills/github/
|No logic in workflow YAML: ADR-006, delegate to scripts

Token savings estimate: ~60-70% per section converted.

Proposed Solution

Phase 1: Compress CRITICAL-CONTEXT.md (Status: READY)

Estimated Effort: S (1-2 hours)
Blockers: None

Task	Description
1.1	Convert "Blocking Constraints" table to pipe-delimited format
1.2	Convert "Session Protocol Gates" to compact list format
1.3	Convert "Skill-First Pattern" tables to pipe-delimited
1.4	Convert "PR Review Comment Routing" tables to pipe-delimited
1.5	Measure before/after token count
1.6	Run session protocol validation to confirm no regression

Expected Outcome: 107 lines to ~60-70 lines, ~1,200 tokens to ~500-600 tokens

Phase 2: Document Decision Framework (Status: READY)

Estimated Effort: S (1 hour)
Blockers: None

Task	Description
2.1	Add "Skill vs Passive Context Decision Framework" section to SKILL-QUICK-REF.md
2.2	Document criteria: Knowledge (passive) vs Actions (skills)
2.3	Add examples of each classification

Phase 3: Optimize memory-index Format (Status: READY)

Estimated Effort: S (1 hour)
Blockers: None

Task	Description
3.1	Convert memory-index.md from table to pipe-delimited index
3.2	Maintain keyword density for lexical discovery
3.3	Validate memory lookup still works via manual testing

Phase 4: Build Eval Suite (Status: PARTIAL)

Estimated Effort: M (4-8 hours)
Blockers: Test infrastructure design decision needed

Recommendation: Defer to separate issue after Phases 1-3 complete.

Phase 5: Skill Pruning Analysis (Status: READY)

Estimated Effort: M (2-4 hours)
Depends On: Phase 2 (framework defines criteria)

Initial Candidates for Review:

• curating-memories - likely knowledge-heavy
• exploring-knowledge-graph - likely knowledge-heavy
• using-forgetful-memory - likely hybrid
• using-serena-symbols - likely hybrid

Phase 6: Automatic Compression Tool (Status: LOW PRIORITY)

Estimated Effort: L (8+ hours)
Recommendation: Defer. Manual compression for 3-4 files is faster than building tooling.

Functional Requirements

FR-1: Compression Format (P0)

ID	Requirement	Acceptance Criteria
FR-1.1	Compressed files MUST use pipe-delimited format	Grep for ^| returns formatted lines
FR-1.2	Section headers MUST use [Section Name] format	Grep for ^\[.*\]$ returns headers
FR-1.3	Compressed files MUST maintain semantic equivalence	Manual review confirms no info loss

FR-2: Token Measurement (P1)

ID	Requirement	Acceptance Criteria
FR-2.1	Before/after token counts MUST be documented	PR description includes measurement
FR-2.2	Total auto-loaded context MUST stay under 10KB	wc -c on files < 10240

FR-3: Protocol Compliance (P0)

ID	Requirement	Acceptance Criteria
FR-3.1	Compressed files MUST pass session validation	Validate-SessionJson.ps1 exit 0
FR-3.2	Skill routing MUST continue to work	"create a PR" routes to github skill

Technical Design

CRITICAL-CONTEXT.md Compression

Current: 107 lines, ~1,200 tokens

Proposed Structure (~65 lines):

# Critical Context (Auto-loaded)

> Pipe-delimited format per Vercel research (80% token reduction).

[Blocking Constraints]
|Python-first (.py): ADR-042, new scripts in Python; PowerShell grandfathered
|No raw gh when skill exists: usage-mandatory, check .claude/skills/github/
|No logic in workflow YAML: ADR-006, delegate to scripts
|Verify branch before git: SESSION-PROTOCOL, git branch --show-current
|HANDOFF.md read-only: ADR-014, never edit
|ADR triggers adr-review: AGENTS.md, multi-agent consensus

[Session Start (BLOCKING)]
|1. Serena init: mcp__serena__activate_project → mcp__serena__initial_instructions
|2. Read HANDOFF.md (read-only dashboard)
|3. Create session log: .agents/sessions/YYYY-MM-DD-session-NN.json
|4. Read usage-mandatory memory
|5. Verify branch: git branch --show-current

[Session End (BLOCKING)]
|1. Complete session log with outcomes
|2. Update Serena memory
|3. Scoped markdownlint (ADR-043)
|4. Route to qa (features only)
|5. Commit all changes
|6. Validate: pwsh scripts/Validate-SessionJson.ps1 -SessionPath [log]
|EXIT: Code 0 required before completion claim

[Skill-First Checkpoint]
|BEFORE any git/gh/script: "Is there a skill for this?"
|CHECK: Scan SKILL-QUICK-REF.md mapping
|USE skill if exists, raw command only if no skill

[Common Skill Mappings]
|Create/manage PRs: github (NOT gh pr create)
|Respond to reviews: pr-comment-responder (NOT gh pr comment)
|Resolve conflicts: merge-resolver (NOT manual git merge)
|Create session log: /session-init (NOT manual JSON)
|Commit and push: /push-pr (NOT git commit && push)

SKILL-QUICK-REF.md Addition

Add "Skill vs Passive Context Framework" section:

[Classification Criteria]
|KNOWLEDGE → passive context: patterns, constraints, routing rules, decision criteria
|ACTIONS → keep as skills: scripts, multi-step workflows, external tool invocations
|HYBRID → split: knowledge in passive context, action scripts in skill directory

[Examples - Knowledge (Passive)]
|Session protocol gates: CRITICAL-CONTEXT.md
|Memory hierarchy: SKILL-QUICK-REF.md
|PR comment routing rules: SKILL-QUICK-REF.md

[Examples - Actions (Skills)]
|Create PR: github skill (requires gh CLI)
|ADR review debate: adr-review skill (multi-agent orchestration)
|Merge conflict resolution: merge-resolver skill (git operations)

memory-index.md Compression

Convert from table to pipe-delimited, grouped by domain:

[Session & Protocol]
|session start init handoff: skills-session-init-index, project-overview
|session validation fixer NON_COMPLIANT: changelog-session-log-fixer

[GitHub Operations]
|github pr issue cli gh: skills-github-cli-index, skills-pr-review-index
|graphql mutation query: skills-graphql-index

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Compressed format breaks parsing	Low	High	Test with Validate-SessionJson.ps1
Token count increases	Low	Medium	Measure before/after; revert if increase
Memory keywords lose discoverability	Medium	Medium	Manual test key scenarios
Skill routing fails	Low	High	Test "create a PR" routing

Success Metrics

Metric	Target
CRITICAL-CONTEXT.md token reduction	>= 40%
memory-index.md token reduction	>= 30%
Total auto-loaded context	< 10KB
Session protocol validation	100% pass

Blocking Questions

Question 1: Eval Suite Framework (Phase 4)

Question: What test framework for protocol compliance eval suite?

Proposed Ask: Defer eval suite to separate issue after Phases 1-3 complete.

Impact if unanswered: Phase 4 blocked. Phases 1-3 can proceed.

Open Questions (Non-Blocking)

1. Should AGENTS.md cite Vercel research? (Likely yes)
2. Are there other files for @import pattern? (Likely no, current structure sufficient)
3. Should memory-index.md be @imported? (No, prevents circular import)

Appendices

Appendix A: Research Sources

Source	URL	Confidence
Vercel Blog	https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals	CONFIRMED
memory-token-efficiency	.serena/memories/memory-token-efficiency.md	CONFIRMED
claude-md-anthropic-best-practices	.serena/memories/claude-md-anthropic-best-practices.md	CONFIRMED

Appendix B: Current File Sizes (2026-02-08)

File	Lines	Est. Tokens
CLAUDE.md	82	~600
CRITICAL-CONTEXT.md	107	~1,200
SKILL-QUICK-REF.md	166	~1,800
memory-index.md	80	~900

Appendix C: Related

• Forgetful memories: IDs 495-502
• ADR-043 (scoped markdownlint)
• Issue labels: documentation, enhancement, agent-qa, agent-memory, area-infrastructure, priority:P2

---

_{Generated by AI PRD Generation | View Workflow}

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The codebase already implements Vercel's passive context strategy with AGENTS.md achieving 100% pass rate. However, key files (CRITICAL-CONTEXT.md, memory-index.md) still use verbose table formats. The research document referenced in the ticket doesn't exist yet - the findings are scattered across AGENTS.md and SKILL-QUICK-REF.md. The compression format example in the ticket shows the target pipe-delimited style already partially implemented in SKILL-QUICK-REF.md (lines 14-18, 28-38, 46-51).

Approach

Apply Vercel's proven compression technique systematically across passive context files. Start with high-impact, low-risk changes (format conversion) before tackling evaluation infrastructure. Prioritize token reduction in auto-loaded files (CRITICAL-CONTEXT.md, memory-index.md) since they're imported via @import in CLAUDE.md. Document the decision framework to prevent future skill/passive context confusion. Defer eval suite and automation tools to later phases as they require more infrastructure investment.

Implementation Steps

High Priority Tasks

1. Create Vercel Research Analysis Document

Create file:.agents/analysis/vercel-passive-context-vs-skills-research.md to consolidate scattered research findings:

• Extract Vercel research data from file:AGENTS.md (lines 1703-1822)
• Extract pass rate table from file:SKILL-QUICK-REF.md (lines 154-164)
• Document the 40KB → 8KB compression achievement
• Include skill classification framework (Horizontal vs Vertical vs Hybrid)
• Add compression format examples with before/after token counts
• Reference the Vercel blog post: https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
• Create corresponding Serena memory with memory_file_name="passive-context-vs-skills-vercel-research"

2. Compress CRITICAL-CONTEXT.md

Convert table-based sections to pipe-delimited format following the pattern in file:SKILL-QUICK-REF.md:

Section: Blocking Constraints (lines 8-16)

• Current: 7-row table with columns (Constraint, Rationale, Verification)
• Target: Pipe-delimited list format
• Example transformation:

  [Blocking Constraints]
  |Python-first (.py preferred): ADR-042 AI/ML alignment → verify new scripts
  |No raw gh when skill exists: Skills tested/validated → check .claude/skills/github/
  |No logic in workflow YAML: ADR-006 testability → delegate to PowerShell
  |Verify branch before git ops: SESSION-PROTOCOL prevent wrong-branch → git branch --show-current
  |HANDOFF.md read-only: ADR-014 distributed handoff → never edit
  |ADR created/edited → adr-review: Multi-agent consensus → run adr-review skill
  |Local workflow test before push: Shift-left catch errors → gh act on changed workflows
  

Section: Session Protocol Gates (lines 20-37)

• Convert numbered lists to pipe-delimited phases
• Follow the compression example from the ticket

Section: Skill-First Pattern (lines 63-72)

• Convert operation table to compressed mapping format
• Maintain the positive checkpoint framing

Section: PR Review Comment Routing (lines 79-100)

• Compress routing tables to pattern detection format

Measure token reduction: Run token counter on original vs compressed versions, document in commit message.

3. Optimize memory-index.md Format

Convert file:.serena/memories/memory-index.md from table format to compressed pipe-delimited:

Current format (lines 3-56): Table with columns (Task Keywords | Essential Memories)

Target format:

[Memory Index]
|session start init handoff protocol serena blocking → skills-session-init-index, project-overview, codebase-structure
|session validation diagnose fixer protocol compliance → changelog-session-log-fixer
|github pr issue cli gh api review comment batch → skills-github-cli-index, skills-pr-review-index, pr-review-batch-response-pattern, project-labels-milestones
|graphql mutation query resolve thread reply batch → skills-graphql-index
|jq json parse filter select map array object → skills-jq-index
...

Engineering Knowledge Tiers section (lines 58-65): Convert to pipe-delimited format

User Constraints section (lines 67-72): Convert to pipe-delimited format

Maintain discoverability by keeping keywords at the start of each line for easy scanning.

4. Document Skill vs Passive Decision Framework

Add new section to file:SKILL-QUICK-REF.md after line 165 (after "Why Passive Context" section):

Section title: "Skill vs Passive Context Decision Framework"

Content structure:

• Decision criteria table: Knowledge → passive context, Actions → skills
• Classification flowchart using Mermaid diagram
• Examples of each category (Horizontal, Vertical, Hybrid)
• Migration checklist for converting skills to passive context
• Token budget guidelines (target: 10KB ceiling for auto-loaded context)

Reference the classification framework from file:AGENTS.md (lines 1730-1766) and compress it to pipe-delimited format.

Medium Priority Tasks

5. Build Eval Suite for Protocol Compliance

Create file:.agents/testing/protocol-compliance-eval-suite.md specification:

Target behaviors (outside model training data):

• Session protocol phase completion verification
• Branch verification before git operations
• Skill-first checkpoint adherence
• Memory-first retrieval pattern
• QA validation gate enforcement

Assertion structure (behavior-based, not implementation):

• Input: Session transcript or session log JSON
• Expected: Protocol compliance checklist completion
• Verification: Parse session log, check required fields exist and are non-empty

Session protocol compliance tests:

• Test 1: Serena initialization occurs before file reads
• Test 2: HANDOFF.md read before work starts
• Test 3: Session log created within first 5 tool calls
• Test 4: Branch verification documented in session log
• Test 5: QA validation ran for feature sessions (or skip evidence documented)

Reference existing validation script file:scripts/Validate-SessionJson.ps1 for structural validation patterns.

Create corresponding test implementation in file:.agents/testing/test_protocol_compliance.py using pytest framework (per ADR-042 Python-first strategy).

6. Skill Pruning Analysis

Create file:.agents/analysis/skill-pruning-candidates.md:

Analysis criteria:

• Identify skills with >70% knowledge content vs action content
• Measure skill invocation frequency from session logs
• Calculate token cost of skill vs passive context equivalent
• Assess conversion feasibility (breaking changes, dependencies)

Candidate identification process:

• Scan file:.claude/skills/ directory for all SKILL.md files
• Classify each skill using Horizontal/Vertical/Hybrid framework
• For Horizontal candidates: Extract knowledge sections, estimate token reduction
• For Hybrid candidates: Identify split points between knowledge and actions

Output: Prioritized list of skills to convert, with estimated token savings and migration effort.

Reference the skill classification from file:AGENTS.md (lines 1738-1766) for initial candidates.

Low Priority Tasks

7. Automatic Context Compression Tool

Create file:.agents/tools/compress-passive-context.py:

Functionality:

• Input: Markdown file path
• Output: Compressed pipe-delimited format
• Compression rules:
  • Tables → pipe-delimited lists
  • Numbered lists → pipe-delimited phases
  • Verbose descriptions → compressed key:value pairs
  • Preserve semantic meaning while reducing tokens

Algorithm:

• Parse markdown AST (use markdown-it-py library)
• Detect table structures, extract columns
• Transform to |column1: value1 → column2: value2 format
• Measure token reduction (before/after)
• Validate compressed output maintains discoverability

Usage:

uv run python .agents/tools/compress-passive-context.py --input CRITICAL-CONTEXT.md --output CRITICAL-CONTEXT-compressed.md --measure-tokens

Apply to @imported files in file:CLAUDE.md to optimize auto-loaded context.

Validation & Measurement

Token Reduction Measurement

For each compressed file:

1. Count tokens before compression (use tiktoken library with cl100k_base encoding)
2. Count tokens after compression
3. Calculate reduction percentage
4. Document in commit message: docs: compress CRITICAL-CONTEXT.md (2.5KB → 1.2KB, 52% reduction)

Pass Rate Validation

After compression changes:

1. Run existing protocol compliance tests: pwsh scripts/Validate-SessionJson.ps1 on recent session logs
2. Verify no regressions in session protocol adherence
3. Check that compressed context maintains discoverability (manual review)
4. Confirm auto-loaded files still parse correctly in CLAUDE.md @import statements

Acceptance Criteria Checklist

• CRITICAL-CONTEXT.md compressed with pipe-delimited format
• Token reduction measured and documented (target: 60-80% reduction)
• Pass rate validation completed (protocol compliance tests pass)
• Decision framework documented in SKILL-QUICK-REF.md
• memory-index.md converted to compressed format
• Vercel research analysis document created at .agents/analysis/vercel-passive-context-vs-skills-research.md
• Serena memory created with ID passive-context-vs-skills-vercel-research

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Research as Research Doc
    participant Critical as CRITICAL-CONTEXT.md
    participant Memory as memory-index.md
    participant SkillRef as SKILL-QUICK-REF.md
    participant Validation as Validation Suite

    Dev->>Research: 1. Create Vercel research analysis
    Research-->>Dev: Document created with findings
    
    Dev->>Critical: 2. Compress tables to pipe-delimited
    Critical-->>Dev: Token count: before/after
    
    Dev->>Memory: 3. Compress memory index
    Memory-->>Dev: Token count: before/after
    
    Dev->>SkillRef: 4. Add decision framework section
    SkillRef-->>Dev: Framework documented
    
    Dev->>Validation: 5. Run protocol compliance tests
    Validation-->>Dev: Pass rate: 100% maintained
    
    Note over Dev,Validation: Medium Priority (Optional)
    Dev->>Validation: 6. Build eval suite
    Dev->>Research: 7. Skill pruning analysis
    
    Note over Dev,Validation: Low Priority (Future)
    Dev->>Dev: 8. Create compression tool

Loading

Related Files

• file:CRITICAL-CONTEXT.md - Primary compression target
• file:SKILL-QUICK-REF.md - Decision framework location, compression pattern reference
• file:.serena/memories/memory-index.md - Memory index compression target
• file:AGENTS.md - Source of Vercel research data (lines 1703-1822)
• file:CLAUDE.md - Entry point with @import statements for auto-loaded context
• file:.agents/SESSION-PROTOCOL.md - Protocol requirements for eval suite
• file:scripts/Validate-SessionJson.ps1 - Existing validation pattern reference

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase already implements Vercel's passive context strategy with AGENTS.md achieving 100% pass rate. However, key files (CRITICAL-CONTEXT.md, memory-index.md) still use verbose table formats. The research document referenced in the ticket doesn't exist yet - the findings are scattered across AGENTS.md and SKILL-QUICK-REF.md. The compression format example in the ticket shows the target pipe-delimited style already partially implemented in SKILL-QUICK-REF.md (lines 14-18, 28-38, 46-51).

## Approach

Apply Vercel's proven compression technique systematically across passive context files. Start with high-impact, low-risk changes (format conversion) before tackling evaluation infrastructure. Prioritize token reduction in auto-loaded files (CRITICAL-CONTEXT.md, memory-index.md) since they're imported via `@import` in CLAUDE.md. Document the decision framework to prevent future skill/passive context confusion. Defer eval suite and automation tools to later phases as they require more infrastructure investment.

## Implementation Steps

### High Priority Tasks

#### 1. Create Vercel Research Analysis Document

Create `file:.agents/analysis/vercel-passive-context-vs-skills-research.md` to consolidate scattered research findings:

- Extract Vercel research data from `file:AGENTS.md` (lines 1703-1822)
- Extract pass rate table from `file:SKILL-QUICK-REF.md` (lines 154-164)
- Document the 40KB → 8KB compression achievement
- Include skill classification framework (Horizontal vs Vertical vs Hybrid)
- Add compression format examples with before/after token counts
- Reference the Vercel blog post: https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
- Create corresponding Serena memory with `memory_file_name="passive-context-vs-skills-vercel-research"`

#### 2. Compress CRITICAL-CONTEXT.md

Convert table-based sections to pipe-delimited format following the pattern in `file:SKILL-QUICK-REF.md`:

**Section: Blocking Constraints (lines 8-16)**
- Current: 7-row table with columns (Constraint, Rationale, Verification)
- Target: Pipe-delimited list format
- Example transformation:
  ```text
  [Blocking Constraints]
  |Python-first (.py preferred): ADR-042 AI/ML alignment → verify new scripts
  |No raw gh when skill exists: Skills tested/validated → check .claude/skills/github/
  |No logic in workflow YAML: ADR-006 testability → delegate to PowerShell
  |Verify branch before git ops: SESSION-PROTOCOL prevent wrong-branch → git branch --show-current
  |HANDOFF.md read-only: ADR-014 distributed handoff → never edit
  |ADR created/edited → adr-review: Multi-agent consensus → run adr-review skill
  |Local workflow test before push: Shift-left catch errors → gh act on changed workflows
  ```

**Section: Session Protocol Gates (lines 20-37)**
- Convert numbered lists to pipe-delimited phases
- Follow the compression example from the ticket

**Section: Skill-First Pattern (lines 63-72)**
- Convert operation table to compressed mapping format
- Maintain the positive checkpoint framing

**Section: PR Review Comment Routing (lines 79-100)**
- Compress routing tables to pattern detection format

Measure token reduction: Run token counter on original vs compressed versions, document in commit message.

#### 3. Optimize memory-index.md Format

Convert `file:.serena/memories/memory-index.md` from table format to compressed pipe-delimited:

**Current format (lines 3-56)**: Table with columns (Task Keywords | Essential Memories)

**Target format**:
```text
[Memory Index]
|session start init handoff protocol serena blocking → skills-session-init-index, project-overview, codebase-structure
|session validation diagnose fixer protocol compliance → changelog-session-log-fixer
|github pr issue cli gh api review comment batch → skills-github-cli-index, skills-pr-review-index, pr-review-batch-response-pattern, project-labels-milestones
|graphql mutation query resolve thread reply batch → skills-graphql-index
|jq json parse filter select map array object → skills-jq-index
...
```

**Engineering Knowledge Tiers section (lines 58-65)**: Convert to pipe-delimited format

**User Constraints section (lines 67-72)**: Convert to pipe-delimited format

Maintain discoverability by keeping keywords at the start of each line for easy scanning.

#### 4. Document Skill vs Passive Decision Framework

Add new section to `file:SKILL-QUICK-REF.md` after line 165 (after "Why Passive Context" section):

**Section title**: "Skill vs Passive Context Decision Framework"

**Content structure**:
- Decision criteria table: Knowledge → passive context, Actions → skills
- Classification flowchart using Mermaid diagram
- Examples of each category (Horizontal, Vertical, Hybrid)
- Migration checklist for converting skills to passive context
- Token budget guidelines (target: 10KB ceiling for auto-loaded context)

Reference the classification framework from `file:AGENTS.md` (lines 1730-1766) and compress it to pipe-delimited format.

### Medium Priority Tasks

#### 5. Build Eval Suite for Protocol Compliance

Create `file:.agents/testing/protocol-compliance-eval-suite.md` specification:

**Target behaviors** (outside model training data):
- Session protocol phase completion verification
- Branch verification before git operations
- Skill-first checkpoint adherence
- Memory-first retrieval pattern
- QA validation gate enforcement

**Assertion structure** (behavior-based, not implementation):
- Input: Session transcript or session log JSON
- Expected: Protocol compliance checklist completion
- Verification: Parse session log, check required fields exist and are non-empty

**Session protocol compliance tests**:
- Test 1: Serena initialization occurs before file reads
- Test 2: HANDOFF.md read before work starts
- Test 3: Session log created within first 5 tool calls
- Test 4: Branch verification documented in session log
- Test 5: QA validation ran for feature sessions (or skip evidence documented)

Reference existing validation script `file:scripts/Validate-SessionJson.ps1` for structural validation patterns.

Create corresponding test implementation in `file:.agents/testing/test_protocol_compliance.py` using pytest framework (per ADR-042 Python-first strategy).

#### 6. Skill Pruning Analysis

Create `file:.agents/analysis/skill-pruning-candidates.md`:

**Analysis criteria**:
- Identify skills with >70% knowledge content vs action content
- Measure skill invocation frequency from session logs
- Calculate token cost of skill vs passive context equivalent
- Assess conversion feasibility (breaking changes, dependencies)

**Candidate identification process**:
- Scan `file:.claude/skills/` directory for all SKILL.md files
- Classify each skill using Horizontal/Vertical/Hybrid framework
- For Horizontal candidates: Extract knowledge sections, estimate token reduction
- For Hybrid candidates: Identify split points between knowledge and actions

**Output**: Prioritized list of skills to convert, with estimated token savings and migration effort.

Reference the skill classification from `file:AGENTS.md` (lines 1738-1766) for initial candidates.

### Low Priority Tasks

#### 7. Automatic Context Compression Tool

Create `file:.agents/tools/compress-passive-context.py`:

**Functionality**:
- Input: Markdown file path
- Output: Compressed pipe-delimited format
- Compression rules:
  - Tables → pipe-delimited lists
  - Numbered lists → pipe-delimited phases
  - Verbose descriptions → compressed key:value pairs
  - Preserve semantic meaning while reducing tokens

**Algorithm**:
- Parse markdown AST (use `markdown-it-py` library)
- Detect table structures, extract columns
- Transform to `|column1: value1 → column2: value2` format
- Measure token reduction (before/after)
- Validate compressed output maintains discoverability

**Usage**:
```bash
uv run python .agents/tools/compress-passive-context.py --input CRITICAL-CONTEXT.md --output CRITICAL-CONTEXT-compressed.md --measure-tokens
```

Apply to `@imported` files in `file:CLAUDE.md` to optimize auto-loaded context.

## Validation & Measurement

### Token Reduction Measurement

For each compressed file:
1. Count tokens before compression (use `tiktoken` library with `cl100k_base` encoding)
2. Count tokens after compression
3. Calculate reduction percentage
4. Document in commit message: `docs: compress CRITICAL-CONTEXT.md (2.5KB → 1.2KB, 52% reduction)`

### Pass Rate Validation

After compression changes:
1. Run existing protocol compliance tests: `pwsh scripts/Validate-SessionJson.ps1` on recent session logs
2. Verify no regressions in session protocol adherence
3. Check that compressed context maintains discoverability (manual review)
4. Confirm auto-loaded files still parse correctly in CLAUDE.md `@import` statements

### Acceptance Criteria Checklist

- [ ] CRITICAL-CONTEXT.md compressed with pipe-delimited format
- [ ] Token reduction measured and documented (target: 60-80% reduction)
- [ ] Pass rate validation completed (protocol compliance tests pass)
- [ ] Decision framework documented in SKILL-QUICK-REF.md
- [ ] memory-index.md converted to compressed format
- [ ] Vercel research analysis document created at `.agents/analysis/vercel-passive-context-vs-skills-research.md`
- [ ] Serena memory created with ID `passive-context-vs-skills-vercel-research`

## Sequence Diagram

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant Research as Research Doc
    participant Critical as CRITICAL-CONTEXT.md
    participant Memory as memory-index.md
    participant SkillRef as SKILL-QUICK-REF.md
    participant Validation as Validation Suite

    Dev->>Research: 1. Create Vercel research analysis
    Research-->>Dev: Document created with findings
    
    Dev->>Critical: 2. Compress tables to pipe-delimited
    Critical-->>Dev: Token count: before/after
    
    Dev->>Memory: 3. Compress memory index
    Memory-->>Dev: Token count: before/after
    
    Dev->>SkillRef: 4. Add decision framework section
    SkillRef-->>Dev: Framework documented
    
    Dev->>Validation: 5. Run protocol compliance tests
    Validation-->>Dev: Pass rate: 100% maintained
    
    Note over Dev,Validation: Medium Priority (Optional)
    Dev->>Validation: 6. Build eval suite
    Dev->>Research: 7. Skill pruning analysis
    
    Note over Dev,Validation: Low Priority (Future)
    Dev->>Dev: 8. Create compression tool
```

## Related Files

- `file:CRITICAL-CONTEXT.md` - Primary compression target
- `file:SKILL-QUICK-REF.md` - Decision framework location, compression pattern reference
- `file:.serena/memories/memory-index.md` - Memory index compression target
- `file:AGENTS.md` - Source of Vercel research data (lines 1703-1822)
- `file:CLAUDE.md` - Entry point with `@import` statements for auto-loaded context
- `file:.agents/SESSION-PROTOCOL.md` - Protocol requirements for eval suite
- `file:scripts/Validate-SessionJson.ps1` - Existing validation pattern reference

---

Execution Information

Branch: main
Commit: 14316db

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","agent-memory","area-infrastructure"]
Priority	P2
Milestone	v1.1
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "agent-memory", "area-infrastructure"],
  "category": "enhancement",
  "confidence": 0.92,
  "reasoning": "Issue requests new compression features and documentation improvements for passive context optimization based on Vercel research findings"
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
The issue aligns with infrastructure optimization and agent memory/context efficiency. No exact epic match exists, but it relates to v1.1 maintainability goals. Evaluating against criteria:

**Priority Assessment:**
- Impact: Medium (improves token efficiency, not blocking core functionality)
- Urgency: Not immediate (current system works)
- Result: P2

**PRD Escalation Criteria Met:**
- Feature Request: Yes (new compression format)
- Multi-Phase Work: Yes (High/Medium/Low priority items)
- Architectural Impact: Yes (affects core context loading)

**Complexity Score:**
- Scope: Multiple files (3) = 2
- Dependencies: Internal only = 2
- Uncertainty: Clear path from research = 1
- Stakeholders: Internal only = 1
- Total: 6

```json
{
  "milestone": "v1.1",
  "priority": "P2",
  "epic_alignment": "",
  "confidence": 0.70,
  "reasoning": "Infrastructure optimization aligned with v1.1 maintainability goals; clear implementation path from Vercel research but not blocking current work",
  "escalate_to_prd": true,
  "escalation_criteria": ["feature_request", "multi_phase_work", "architectural_impact"],
  "complexity_score": 6
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>