Skill Evolve

Skill Evolve (Optional Sidecar)

This is an OPTIONAL sidecar capability, NOT part of the default pipeline.

What This Skill Is

Skill Evolve is a controlled, opt-in framework for turning real user feedback into skill improvements over time.

It is designed to:

• Collect and normalize user feedback
• Generate minimal patch proposals
• Require manual review/refinement of generated patch proposals before real patch application
• Test reviewed patches in isolated workspaces
• Run regression gates
• Promote verified patches to new stable versions
• Preserve the default .cursor/skills/ tree unchanged unless a human later chooses to merge approved changes manually

What This Skill Is NOT

This skill must NOT:

• Run automatically during normal report generation
• Modify stable skills without explicit evolve flow
• Replace human judgment with automated decisions
• Make the default pipeline behave differently

When to Use This Skill

Use this skill when:

• User explicitly requests "skill evolution" or "feedback-driven improvement"
• User provides feedback that should be tracked and potentially addressed
• User wants to analyze and improve the skill framework

Do NOT use this skill when:

• Generating reports (use one-report instead)
• Running normal pipeline operations
• User has not explicitly requested skill evolution

Controlled Evolve Loop Flow

When explicitly invoked, follow this controlled flow:

Step 1: Collect Feedback

Use collect_feedback.py to ingest raw user feedback:

python .cursor/skills/skill-evolve/scripts/collect_feedback.py --interactive
# OR
python .cursor/skills/skill-evolve/scripts/collect_feedback.py --text "feedback text"
# OR
python .cursor/skills/skill-evolve/scripts/collect_feedback.py --file /path/to/feedback.txt

Raw feedback preserves user language and is saved to: {WORKSPACE}/.skill-evolve-data/feedback/raw/

Step 2: Normalize Feedback

Convert raw feedback to structured format:

python .cursor/skills/skill-evolve/scripts/normalize_feedback.py \
    --feedback-id FB-XXXXXX \
    --stage <grounding|research|summary|review|export> \
    --skill <skill-name>

Normalized feedback is saved to: {WORKSPACE}/.skill-evolve-data/feedback/normalized/

Step 3: Propose Minimal Patch

Generate a patch proposal from normalized feedback:

python .cursor/skills/skill-evolve/scripts/propose_skill_patch.py \
    --feedback-id FB-XXXXXX,FB-YYYYYY

Patch proposals are saved to: {WORKSPACE}/.skill-evolve-data/patch_proposals/proposed/

Change Unit

A patch proposal is not just a single modified skill file, but a complete change unit containing:

1. Main File: The skill being modified
2. Dependency References: All other skills/agent configs that reference this skill
3. Auto-generated Assertions: For regression gate verification

Dependency Reference Scanning

When generating a proposal, the agent must:

1. Identify Main File: Determine which skill is the modification target
2. Scan Dependencies: Search all skills and agent configs to find references to the main file
   • Check other skills' "What This Skill Is" or invocation chain descriptions
   • Check agent configs for skill references
   • Check prompting templates for skill paths
3. Declare Reference Points: List all locations requiring sync updates in the proposal
4. Analyze Impact Scope: Distinguish between "description update only" and "behavior sync required" references

Example: If the modification target is grounded-review:

• Main File: .cursor/skills/grounded-review/SKILL.md
• Dependency References:
  • .cursor/skills/one-report/SKILL.md (as sub-process reference)
  • .cursor/agents/reviewer.md (agent config)

Auto-generated Assertions

The proposal script should auto-generate assertions rather than relying on manual creation:

1. Analyze planned_changes:

   • If before content exists → generate not_contains assertion to verify old content removed
   • If after content exists → generate contains assertion to verify new content added
   • Numeric changes (90→95) → generate regex_match assertion

2. Minimal Assertion Set:

   • Core semantic changes must be covered by assertions
   • Avoid redundant assertions (one contains can verify content without splitting)
   • Empty tests cannot pass vacuously (reject if no changes)

3. Cross-file Assertions:

   • If dependency references also need updates, those points should have corresponding assertions
   • Ensure consistency between main file and reference points

Auto-generated Assertion Example (threshold 90→95):

{
  "assertions": [
    {
      "name": "threshold_updated_to_95",
      "type": "contains",
      "file": "grounded-review/SKILL.md",
      "pattern": "weighted total >= 95"
    },
    {
      "name": "old_threshold_90_removed",
      "type": "not_contains",
      "file": "grounded-review/SKILL.md",
      "pattern": "weighted total >= 90"
    },
    {
      "name": "one_report_sync",
      "type": "contains",
      "file": "one-report/SKILL.md",
      "pattern": "review threshold"
    }
  ]
}

Step 4: Review and Refine Patch Proposal

Before applying any changes, review and refine the proposed planned_changes so they contain concrete, safe edits.

Do not treat an auto-generated proposal as ready-to-apply by default.

Step 5: Apply Patch Candidate

Apply the reviewed patch to an isolated workspace for testing:

python .cursor/skills/skill-evolve/scripts/apply_patch_to_workspace.py \
    --proposal-id PP-XXXXXX \
    --apply-changes

This creates a candidate workspace without modifying stable skills.

Step 6: Run Regression Gate

Test the patch against evaluation cases:

python .cursor/skills/skill-evolve/scripts/run_regression_gate.py \
    --proposal-id PP-XXXXXX

Results are saved to: {WORKSPACE}/.skill-evolve-data/evaluations/results/

Regression Gate for Change Units

Regression gate must verify the complete change unit:

1. Main File Assertions: Verify core changes in the main skill file
2. Dependency Reference Assertions: Verify sync updates for all dependency reference points
3. Consistency Checks: Ensure descriptions/behaviors match between main file and references

Assertion File Path Resolution

The file field in assertions is resolved relative to workspace root:

• grounded-review/SKILL.md → {workspace}/grounded-review/SKILL.md
• one-report/SKILL.md → {workspace}/one-report/SKILL.md
• .cursor/agents/reviewer.md → {workspace}/.cursor/agents/reviewer.md