@vodailoc/kilo-kit-mcp 1.1.0 → 1.1.1

package/skills/engineering/context-engineering/references/context-degradation.md

@@ -1,93 +1,93 @@
-# Context Degradation Patterns
-
-Predictable degradation as context grows. Not binary - a continuum.
-
-## Degradation Patterns
-
-| Pattern | Cause | Detection |
-|---------|-------|-----------|
-| **Lost-in-Middle** | U-shaped attention | Critical info recall drops 10-40% |
-| **Context Poisoning** | Errors compound via reference | Persistent hallucinations despite correction |
-| **Context Distraction** | Irrelevant info overwhelms | Single distractor degrades performance |
-| **Context Confusion** | Multiple tasks mix | Wrong tool calls, mixed requirements |
-| **Context Clash** | Contradictory info | Conflicting outputs, inconsistent reasoning |
-
-## Lost-in-Middle Phenomenon
-
-- Information in middle gets 10-40% lower recall
-- Models allocate massive attention to first token (BOS sink)
-- As context grows, middle tokens fail to get sufficient attention
-- **Mitigation**: Place critical info at beginning/end
-
-```markdown
-[CURRENT TASK]              # Beginning - high attention
-- Critical requirements
-
-[DETAILED CONTEXT]          # Middle - lower attention
-- Supporting details
-
-[KEY FINDINGS]              # End - high attention
-- Important conclusions
-```
-
-## Context Poisoning
-
-**Entry points**:
-1. Tool outputs with errors/unexpected formats
-2. Retrieved docs with incorrect/outdated info
-3. Model-generated summaries with hallucinations
-
-**Detection symptoms**:
-- Degraded quality on previously successful tasks
-- Tool misalignment (wrong tools/parameters)
-- Persistent hallucinations
-
-**Recovery**:
-- Truncate to before poisoning point
-- Explicit note + re-evaluation request
-- Restart with clean context, preserve only verified info
-
-## Model Degradation Thresholds
-
-| Model | Degradation Onset | Severe Degradation |
-|-------|-------------------|-------------------|
-| GPT-5.2 | ~64K tokens | ~200K tokens |
-| Claude Opus 4.5 | ~100K tokens | ~180K tokens |
-| Claude Sonnet 4.5 | ~80K tokens | ~150K tokens |
-| Gemini 3 Pro | ~500K tokens | ~800K tokens |
-
-## Four-Bucket Mitigation
-
-1. **Write**: Save externally (scratchpads, files)
-2. **Select**: Pull only relevant (retrieval, filtering)
-3. **Compress**: Reduce tokens (summarization)
-4. **Isolate**: Split across sub-agents (partitioning)
-
-## Detection Heuristics
-
-```python
-def calculate_health(utilization, degradation_risk, poisoning_risk):
-    """Health score: 1.0 = healthy, 0.0 = critical"""
-    score = 1.0
-    score -= utilization * 0.5 if utilization > 0.7 else 0
-    score -= degradation_risk * 0.3
-    score -= poisoning_risk * 0.2
-    return max(0, score)
-
-# Thresholds: healthy >0.8, warning >0.6, degraded >0.4, critical <=0.4
-```
-
-## Guidelines
-
-1. Monitor context length vs performance correlation
-2. Place critical info at beginning/end
-3. Implement compaction before degradation
-4. Validate retrieved docs before adding
-5. Use versioning to prevent outdated clash
-6. Segment tasks to prevent confusion
-7. Design for graceful degradation
-
-## Related Topics
-
-- [Context Optimization](./context-optimization.md) - Mitigation techniques
-- [Multi-Agent Patterns](./multi-agent-patterns.md) - Isolation strategies
+# Context Degradation Patterns
+
+Predictable degradation as context grows. Not binary - a continuum.
+
+## Degradation Patterns
+
+| Pattern | Cause | Detection |
+|---------|-------|-----------|
+| **Lost-in-Middle** | U-shaped attention | Critical info recall drops 10-40% |
+| **Context Poisoning** | Errors compound via reference | Persistent hallucinations despite correction |
+| **Context Distraction** | Irrelevant info overwhelms | Single distractor degrades performance |
+| **Context Confusion** | Multiple tasks mix | Wrong tool calls, mixed requirements |
+| **Context Clash** | Contradictory info | Conflicting outputs, inconsistent reasoning |
+
+## Lost-in-Middle Phenomenon
+
+- Information in middle gets 10-40% lower recall
+- Models allocate massive attention to first token (BOS sink)
+- As context grows, middle tokens fail to get sufficient attention
+- **Mitigation**: Place critical info at beginning/end
+
+```markdown
+[CURRENT TASK]              # Beginning - high attention
+- Critical requirements
+
+[DETAILED CONTEXT]          # Middle - lower attention
+- Supporting details
+
+[KEY FINDINGS]              # End - high attention
+- Important conclusions
+```
+
+## Context Poisoning
+
+**Entry points**:
+1. Tool outputs with errors/unexpected formats
+2. Retrieved docs with incorrect/outdated info
+3. Model-generated summaries with hallucinations
+
+**Detection symptoms**:
+- Degraded quality on previously successful tasks
+- Tool misalignment (wrong tools/parameters)
+- Persistent hallucinations
+
+**Recovery**:
+- Truncate to before poisoning point
+- Explicit note + re-evaluation request
+- Restart with clean context, preserve only verified info
+
+## Model Degradation Thresholds
+
+| Model | Degradation Onset | Severe Degradation |
+|-------|-------------------|-------------------|
+| GPT-5.2 | ~64K tokens | ~200K tokens |
+| Claude Opus 4.5 | ~100K tokens | ~180K tokens |
+| Claude Sonnet 4.5 | ~80K tokens | ~150K tokens |
+| Gemini 3 Pro | ~500K tokens | ~800K tokens |
+
+## Four-Bucket Mitigation
+
+1. **Write**: Save externally (scratchpads, files)
+2. **Select**: Pull only relevant (retrieval, filtering)
+3. **Compress**: Reduce tokens (summarization)
+4. **Isolate**: Split across sub-agents (partitioning)
+
+## Detection Heuristics
+
+```python
+def calculate_health(utilization, degradation_risk, poisoning_risk):
+    """Health score: 1.0 = healthy, 0.0 = critical"""
+    score = 1.0
+    score -= utilization * 0.5 if utilization > 0.7 else 0
+    score -= degradation_risk * 0.3
+    score -= poisoning_risk * 0.2
+    return max(0, score)
+
+# Thresholds: healthy >0.8, warning >0.6, degraded >0.4, critical <=0.4
+```
+
+## Guidelines
+
+1. Monitor context length vs performance correlation
+2. Place critical info at beginning/end
+3. Implement compaction before degradation
+4. Validate retrieved docs before adding
+5. Use versioning to prevent outdated clash
+6. Segment tasks to prevent confusion
+7. Design for graceful degradation
+
+## Related Topics
+
+- [Context Optimization](./context-optimization.md) - Mitigation techniques
+- [Multi-Agent Patterns](./multi-agent-patterns.md) - Isolation strategies

package/skills/engineering/context-engineering/references/context-fundamentals.md

@@ -1,75 +1,75 @@
-# Context Fundamentals
-
-Context = all input provided to LLM for task completion.
-
-## Anatomy of Context
-
-| Component | Purpose | Token Impact |
-|-----------|---------|--------------|
-| System Prompt | Identity, constraints, guidelines | Stable, cacheable |
-| Tool Definitions | Action specs with params/returns | Grows with capabilities |
-| Retrieved Docs | Domain knowledge, just-in-time | Variable, selective |
-| Message History | Conversation state, task progress | Accumulates over time |
-| Tool Outputs | Results from actions | 83.9% of typical context |
-
-## Attention Mechanics
-
-- **U-shaped curve**: Beginning/end get more attention than middle
-- **Attention budget**: n^2 relationships for n tokens depletes with growth
-- **Position encoding**: Interpolation allows longer sequences with degradation
-- **First-token sink**: BOS token absorbs large attention budget
-
-## System Prompt Structure
-
-```xml
-<BACKGROUND_INFORMATION>Domain knowledge, role definition</BACKGROUND_INFORMATION>
-<INSTRUCTIONS>Step-by-step procedures</INSTRUCTIONS>
-<TOOL_GUIDANCE>When/how to use tools</TOOL_GUIDANCE>
-<OUTPUT_DESCRIPTION>Format requirements</OUTPUT_DESCRIPTION>
-```
-
-## Progressive Disclosure Levels
-
-1. **Metadata** (~100 words) - Always in context
-2. **SKILL.md body** (<5k words) - When skill triggers
-3. **Bundled resources** (Unlimited) - As needed
-
-## Token Budget Allocation
-
-| Component | Typical Range | Notes |
-|-----------|---------------|-------|
-| System Prompt | 500-2000 | Stable, optimize once |
-| Tool Definitions | 100-500 per tool | Keep under 20 tools |
-| Retrieved Docs | 1000-5000 | Selective loading |
-| Message History | Variable | Summarize at 70% |
-| Reserved Buffer | 10-20% | For responses |
-
-## Document Management
-
-**Strong identifiers**: `customer_pricing_rates.json` not `data/file1.json`
-**Chunk at semantic boundaries**: Paragraphs, sections, not arbitrary lengths
-**Include metadata**: Source, date, relevance score
-
-## Message History Pattern
-
-```python
-# Summary injection every 20 messages
-if len(messages) % 20 == 0:
-    summary = summarize_conversation(messages[-20:])
-    messages.append({"role": "system", "content": f"Summary: {summary}"})
-```
-
-## Guidelines
-
-1. Treat context as finite with diminishing returns
-2. Place critical info at attention-favored positions
-3. Use file-system-based access for large documents
-4. Pre-load stable content, just-in-time load dynamic
-5. Design with explicit token budgets
-6. Monitor usage, implement compaction triggers at 70-80%
-
-## Related Topics
-
-- [Context Degradation](./context-degradation.md) - Failure patterns
-- [Context Optimization](./context-optimization.md) - Efficiency techniques
-- [Memory Systems](./memory-systems.md) - External storage
+# Context Fundamentals
+
+Context = all input provided to LLM for task completion.
+
+## Anatomy of Context
+
+| Component | Purpose | Token Impact |
+|-----------|---------|--------------|
+| System Prompt | Identity, constraints, guidelines | Stable, cacheable |
+| Tool Definitions | Action specs with params/returns | Grows with capabilities |
+| Retrieved Docs | Domain knowledge, just-in-time | Variable, selective |
+| Message History | Conversation state, task progress | Accumulates over time |
+| Tool Outputs | Results from actions | 83.9% of typical context |
+
+## Attention Mechanics
+
+- **U-shaped curve**: Beginning/end get more attention than middle
+- **Attention budget**: n^2 relationships for n tokens depletes with growth
+- **Position encoding**: Interpolation allows longer sequences with degradation
+- **First-token sink**: BOS token absorbs large attention budget
+
+## System Prompt Structure
+
+```xml
+<BACKGROUND_INFORMATION>Domain knowledge, role definition</BACKGROUND_INFORMATION>
+<INSTRUCTIONS>Step-by-step procedures</INSTRUCTIONS>
+<TOOL_GUIDANCE>When/how to use tools</TOOL_GUIDANCE>
+<OUTPUT_DESCRIPTION>Format requirements</OUTPUT_DESCRIPTION>
+```
+
+## Progressive Disclosure Levels
+
+1. **Metadata** (~100 words) - Always in context
+2. **SKILL.md body** (<5k words) - When skill triggers
+3. **Bundled resources** (Unlimited) - As needed
+
+## Token Budget Allocation
+
+| Component | Typical Range | Notes |
+|-----------|---------------|-------|
+| System Prompt | 500-2000 | Stable, optimize once |
+| Tool Definitions | 100-500 per tool | Keep under 20 tools |
+| Retrieved Docs | 1000-5000 | Selective loading |
+| Message History | Variable | Summarize at 70% |
+| Reserved Buffer | 10-20% | For responses |
+
+## Document Management
+
+**Strong identifiers**: `customer_pricing_rates.json` not `data/file1.json`
+**Chunk at semantic boundaries**: Paragraphs, sections, not arbitrary lengths
+**Include metadata**: Source, date, relevance score
+
+## Message History Pattern
+
+```python
+# Summary injection every 20 messages
+if len(messages) % 20 == 0:
+    summary = summarize_conversation(messages[-20:])
+    messages.append({"role": "system", "content": f"Summary: {summary}"})
+```
+
+## Guidelines
+
+1. Treat context as finite with diminishing returns
+2. Place critical info at attention-favored positions
+3. Use file-system-based access for large documents
+4. Pre-load stable content, just-in-time load dynamic
+5. Design with explicit token budgets
+6. Monitor usage, implement compaction triggers at 70-80%
+
+## Related Topics
+
+- [Context Degradation](./context-degradation.md) - Failure patterns
+- [Context Optimization](./context-optimization.md) - Efficiency techniques
+- [Memory Systems](./memory-systems.md) - External storage

package/skills/engineering/context-engineering/references/context-optimization.md

@@ -1,82 +1,82 @@
-# Context Optimization
-
-Extend effective context capacity through strategic techniques.
-
-## Four Core Strategies
-
-| Strategy | Target | Reduction | When to Use |
-|----------|--------|-----------|-------------|
-| **Compaction** | Full context | 50-70% | Approaching limits |
-| **Observation Masking** | Tool outputs | 60-80% | Verbose outputs >80% |
-| **KV-Cache Optimization** | Repeated prefixes | 70%+ hit | Stable prompts |
-| **Context Partitioning** | Work distribution | N/A | Parallelizable tasks |
-
-## Compaction
-
-Summarize context when approaching limits.
-
-**Priority**: Tool outputs → Old turns → Retrieved docs → Never: System prompt
-
-```python
-if context_tokens / context_limit > 0.8:
-    context = compact_context(context)
-```
-
-**Preserve**: Key findings, decisions, commitments (remove supporting details)
-
-## Observation Masking
-
-Replace verbose tool outputs with compact references.
-
-```python
-if len(observation) > max_length:
-    ref_id = store_observation(observation)
-    return f"[Obs:{ref_id}. Key: {extract_key(observation)}]"
-```
-
-**Never mask**: Current task critical, most recent turn, active reasoning
-**Always mask**: Repeated outputs, boilerplate, already summarized
-
-## KV-Cache Optimization
-
-Reuse cached Key/Value tensors for identical prefixes.
-
-```python
-# Cache-friendly ordering (stable first)
-context = [system_prompt, tool_definitions]  # Cacheable
-context += [unique_content]                   # Variable last
-```
-
-**Tips**: Avoid timestamps in stable sections, consistent formatting, stable structure
-
-## Context Partitioning
-
-Split work across sub-agents with isolated contexts.
-
-```python
-result = await sub_agent.process(subtask, clean_context=True)
-coordinator.receive(result.summary)  # Only essentials
-```
-
-## Decision Framework
-
-| Dominant Component | Apply |
-|-------------------|-------|
-| Tool outputs | Observation masking |
-| Retrieved docs | Summarization or partitioning |
-| Message history | Compaction + summarization |
-| Multiple | Combine strategies |
-
-## Guidelines
-
-1. Measure before optimizing
-2. Apply compaction before masking
-3. Design for cache stability
-4. Partition before context problematic
-5. Monitor effectiveness over time
-6. Balance savings vs quality
-
-## Related
-
-- [Context Compression](./context-compression.md)
-- [Memory Systems](./memory-systems.md)
+# Context Optimization
+
+Extend effective context capacity through strategic techniques.
+
+## Four Core Strategies
+
+| Strategy | Target | Reduction | When to Use |
+|----------|--------|-----------|-------------|
+| **Compaction** | Full context | 50-70% | Approaching limits |
+| **Observation Masking** | Tool outputs | 60-80% | Verbose outputs >80% |
+| **KV-Cache Optimization** | Repeated prefixes | 70%+ hit | Stable prompts |
+| **Context Partitioning** | Work distribution | N/A | Parallelizable tasks |
+
+## Compaction
+
+Summarize context when approaching limits.
+
+**Priority**: Tool outputs → Old turns → Retrieved docs → Never: System prompt
+
+```python
+if context_tokens / context_limit > 0.8:
+    context = compact_context(context)
+```
+
+**Preserve**: Key findings, decisions, commitments (remove supporting details)
+
+## Observation Masking
+
+Replace verbose tool outputs with compact references.
+
+```python
+if len(observation) > max_length:
+    ref_id = store_observation(observation)
+    return f"[Obs:{ref_id}. Key: {extract_key(observation)}]"
+```
+
+**Never mask**: Current task critical, most recent turn, active reasoning
+**Always mask**: Repeated outputs, boilerplate, already summarized
+
+## KV-Cache Optimization
+
+Reuse cached Key/Value tensors for identical prefixes.
+
+```python
+# Cache-friendly ordering (stable first)
+context = [system_prompt, tool_definitions]  # Cacheable
+context += [unique_content]                   # Variable last
+```
+
+**Tips**: Avoid timestamps in stable sections, consistent formatting, stable structure
+
+## Context Partitioning
+
+Split work across sub-agents with isolated contexts.
+
+```python
+result = await sub_agent.process(subtask, clean_context=True)
+coordinator.receive(result.summary)  # Only essentials
+```
+
+## Decision Framework
+
+| Dominant Component | Apply |
+|-------------------|-------|
+| Tool outputs | Observation masking |
+| Retrieved docs | Summarization or partitioning |
+| Message history | Compaction + summarization |
+| Multiple | Combine strategies |
+
+## Guidelines
+
+1. Measure before optimizing
+2. Apply compaction before masking
+3. Design for cache stability
+4. Partition before context problematic
+5. Monitor effectiveness over time
+6. Balance savings vs quality
+
+## Related
+
+- [Context Compression](./context-compression.md)
+- [Memory Systems](./memory-systems.md)