skill-integration

# Skill-Creator Integration Manages skill loading, observation, and bounded learning for the GSD ecosystem. Ensures learned knowledge persists across sessions and subagent contexts. ## Skill Loading Before GSD Phases Before executing any GSD phase, load relevant generated skills: 1. Check `.claude/commands/` for project-level skills 2. Check `~/.claude/commands/` for user-level skills 3. Project-level skills take precedence over user-level on conflict 4. Load only skills relevant to the current phase and task 5. Respect the token budget: 2-5% of context window maximum **Critical:** When forking subagent contexts for GSD phases (`execute-phase`, `verify-work`), include relevant skills in the subagent's context. Clean context means free of stale conversation history -- not free of learned knowledge. A subagent that can't access learned skills is throwing away everything skill-creator has captured. For full 6-stage pipeline details, see `references/loading-protocol.md`. ## Token Budget Management The 6-stage skill loading pipeline (Score, Resolve, ModelFilter, CacheOrder, Budget, Load) manages what gets loaded. When multiple skills compete for budget: 1. Phase-relevant skills get priority (e.g., testing skills during `verify-work`) 2. Recently activated skills rank higher than dormant ones 3. Project-level skills override user-level duplicates 4. If budget is exceeded, queue overflow skills and note what was deferred ## Session Observation Protocol During all work sessions, maintain awareness of patterns worth capturing: - Tool sequences that repeat across sessions (e.g., `git log -> read file -> edit -> test -> commit`) - File patterns consistently touched during specific GSD phases - Commands run after test failures or verification issues - Corrections the user makes to agent output -- these are the highest-signal observations - Phase outcomes: success, failure, partial, and what was different If `.planning/patterns/` exists, record observations to `sessions.jsonl` in that directory. This data feeds skill-creator's pattern detection pipeline. For observation taxonomy, signal strength ranking, and JSONL schema, see `references/observation-patterns.md`. ## Bounded Learning Guardrails **These constraints are NON-NEGOTIABLE:** - Maximum 20% content change per skill refinement - Minimum 3 corrections before a refinement is proposed - 7-day cooldown between refinements of the same skill - All refinements require user confirmation - Skill generation never skips permission checks - Agent composition requires 5+ co-activations over 7+ days For rationale and enforcement details, see `references/bounded-guardrails.md`. ## Phase Transition Hooks After completing any GSD phase transition, check for skills that should trigger: | GSD Event | Check For | |-----------|-----------| | `plan-phase` completes | Skills triggered by planning completion, docs regeneration | | `execute-phase` completes | Skills triggered by execution progress, state updates | | `verify-work` completes | Skills triggered by verification results, test patterns | | `complete-milestone` completes | Skills triggered by milestone completion, docs finalization | | Any `.planning/` file write | Dashboard regeneration if gsd-planning-docs skill is installed | Run matching skills **after** the phase completes, not during -- avoid adding overhead to the critical path. ## Skill Suggestions At the start of each new session, check skill-creator for pending suggestions. If suggestions exist with high confidence (3+ pattern occurrences), briefly notify the user: > "skill-creator detected a repeating pattern: [brief description]. Run `skill-creator suggest` to review." **Never auto-apply suggestions. Always require explicit user confirmation.** This is a core safety principle of the bounded learning system. ## When to Suggest skill-creator **Suggest skill-creator when:** - You notice the same sequence of steps has occurred 3+ times - The user corrects the same kind of output repeatedly - A workflow is complex enough to benefit from codification - The user asks "why do I keep having to tell you this?" **Suggest naturally:** ``` I've noticed we run the same lint -> test -> fix cycle after every code change. Want me to capture this as a skill so it happens automatically? ``` ## Auditing a Skill (counterfactual) Pass-rate is blind to most skill effects — a skill can change behavior in hundreds of ways while pass-rate barely moves. **When a skill is created, modified, or proposed for retirement, run the `skill-counterfactual-audit` skill** before finalizing. It runs a paired probe (the same task once with the skill loaded and once without), segments and aligns both traces into goal-directed phases, and emits a SIP report (surface anchoring, template copy, excess planning, task recovery, off-task artifact). Treat its findings as the behavioral-impact signal pass-rate cannot give you: a low-impact skill is a retirement candidate; a high-negative-impact skill needs revision, not just a green test. This is the audit gate for the skill lifecycle this skill manages. ## Anti-Patterns - Do not execute GSD phases without checking for relevant learned skills first - Do not auto-apply skill suggestions -- always require user confirmation - Do not load skills that exceed the token budget -- defer and note what was skipped - Do not ignore user corrections -- they are the primary signal for skill refinement