Skill Tuning

Autonomous diagnosis and optimization for skill execution issues.

Architecture

┌─────────────────────────────────────────────────────┐ │ Phase 0: Read Specs (mandatory) │ │ → problem-taxonomy.md, tuning-strategies.md │ └─────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────┐ │ Orchestrator (state-driven) │ │ Read state → Select action → Execute → Update → ✓ │ └─────────────────────────────────────────────────────┘ ↓ ↓ ┌──────────────────────┐ ┌──────────────────┐ │ Diagnosis Phase │ │ Gemini CLI │ │ • Context │ │ Deep analysis │ │ • Memory │ │ (on-demand) │ │ • DataFlow │ │ │ │ • Agent │ │ Complex issues │ │ • Docs │ │ Architecture │ │ • Token Usage │ │ Performance │ └──────────────────────┘ └──────────────────┘ ↓ ┌───────────────────┐ │ Fix & Verify │ │ Apply → Re-test │ └───────────────────┘

Core Issues Detected

Priority Problem Root Cause Fix Strategy

P0 Authoring Violation Intermediate files, state bloat, file relay eliminate_intermediate, minimize_state

P1 Data Flow Disruption Scattered state, inconsistent formats state_centralization, schema_enforcement

P2 Agent Coordination Fragile chains, no error handling error_wrapping, result_validation

P3 Context Explosion Unbounded history, full content passing sliding_window, path_reference

P4 Long-tail Forgetting Early constraint loss constraint_injection, checkpoint_restore

P5 Token Consumption Verbose prompts, state bloat prompt_compression, lazy_loading

Problem Categories (Detailed Specs)

See specs/problem-taxonomy.md for:

• Detection patterns (regex/checks)

• Severity calculations

• Impact assessments

Tuning Strategies (Detailed Specs)

See specs/tuning-strategies.md for:

• 10+ strategies per category

• Implementation patterns

• Verification methods

Workflow

Step Action Orchestrator Decision Output

1 action-init

status='pending' Backup, session created

2 action-analyze-requirements

After init Required dimensions + coverage

3 Diagnosis (6 types) Focus areas state.diagnosis.{type}

4 action-gemini-analysis

Critical issues OR user request Deep findings

5 action-generate-report

All diagnosis complete state.final_report

6 action-propose-fixes

Issues found state.proposed_fixes[]

7 action-apply-fix

Pending fixes Applied + verified

8 action-complete

Quality gates pass session.status='completed'

Action Reference

Category Actions Purpose

Setup action-init Initialize backup, session state

Analysis action-analyze-requirements Decompose user request via Gemini CLI

Diagnosis action-diagnose-{context,memory,dataflow,agent,docs,token_consumption} Detect category-specific issues

Deep Analysis action-gemini-analysis Gemini CLI: complex/critical issues

Reporting action-generate-report Consolidate findings → final_report

Fixing action-propose-fixes, action-apply-fix Generate + apply fixes

Verify action-verify Re-run diagnosis, check gates

Exit action-complete, action-abort Finalize or rollback

Full action details: phases/actions/

State Management

Single source of truth: .workflow/.scratchpad/skill-tuning-{ts}/state.json

{ "status": "pending|running|completed|failed", "target_skill": { "name": "...", "path": "..." }, "diagnosis": { "context": {...}, "memory": {...}, "dataflow": {...}, "agent": {...}, "docs": {...}, "token_consumption": {...} }, "issues": [{"id":"...", "severity":"...", "category":"...", "strategy":"..."}], "proposed_fixes": [...], "applied_fixes": [...], "quality_gate": "pass|fail", "final_report": "..." }

See phases/state-schema.md for complete schema.

Orchestrator Logic

See phases/orchestrator.md for:

• Decision logic (termination checks → action selection)

• State transitions

• Error recovery

Key Principles

• Problem-First: Diagnosis before any fix

• Data-Driven: Record traces, token counts, snapshots

• Iterative: Multiple rounds until quality gates pass

• Reversible: All changes with backup checkpoints

• Non-Invasive: Minimal changes, maximum clarity

Usage Examples

Basic skill diagnosis

/skill-tuning "Fix memory leaks in my skill"

Deep analysis with Gemini

/skill-tuning "Architecture issues in async workflow"

Focus on specific areas

/skill-tuning "Optimize token consumption and fix agent coordination"

Custom issue

/skill-tuning "My skill produces inconsistent outputs"

Output

After completion, review:

• .workflow/.scratchpad/skill-tuning-{ts}/state.json

• Full state with final_report

• state.final_report

• Markdown summary (in state.json)

• state.applied_fixes

• List of applied fixes with verification results

Reference Documents

Document Purpose

specs/problem-taxonomy.md Classification + detection patterns

specs/tuning-strategies.md Fix implementation guide

specs/dimension-mapping.md Dimension ↔ Spec mapping

specs/quality-gates.md Quality verification criteria

phases/orchestrator.md Workflow orchestration

phases/state-schema.md State structure definition

phases/actions/ Individual action implementations