lawvable/skill-optimizer-lawvable

Self-Improve Skill

Analyze the current conversation and propose improvements to skills based on corrections, successes, and edge cases discovered during the work session.

Triggers

• self-improve - Analyze session and propose improvements
• self-improve [skill-name] - Target a specific skill
• self-improve on - Enable automatic mode (hook)
• self-improve off - Disable automatic mode
• self-improve status - Show automatic mode status
• self-improve [skill-name] history - Show modification history

---

Main Workflow (self-improve)

Step 1: Identify the Skill

If skill name not provided, list available skills from skills/ directory and ask:

Which skill should I analyze for this session?
[List skills found in skills/ directory]

Step 2: Detect Signals

Scan the conversation for signals - moments where the user expressed feedback:

| Signal Type | Examples | |-------------|----------| | Correction | "No", "That's not right", "It's missing X", "Always do Y", user rewrites output | | Success | "Perfect", "Yes", "Exactly", user accepts without changes | | Edge case | User needed a workaround, skill couldn't handle the request |

Step 3: Evaluate Each Signal for Quality

For each correction signal, evaluate if it can become a good skill instruction.

Quality Criteria

1. COMPLETE

The instruction includes all information needed to apply it. No need to look elsewhere or make assumptions.

| Grade | Example | |-------|---------| | Pass | "Structure output as: Key Terms / Risk Areas / Suggested Revisions" | | Fail | "Use the standard format" (which format?) | | Fail | "Follow our firm's guidelines" (what guidelines?) |

2. PRECISE

No vague or subjective terms. Two different people reading the instruction would understand it the same way.

| Grade | Example | |-------|---------| | Pass | "Flag non-compete clauses over 12 months as high risk" | | Fail | "Be more thorough in the analysis" | | Fail | "Make it more appropriate for clients" |

3. ATOMIC

One instruction addresses one single requirement. Multiple checks should be split into separate instructions.

| Grade | Example | |-------|---------| | Pass | "Check for governing law clause" | | Fail | "Check for governing law, jurisdiction, and arbitration clauses" (three checks - split them) |

4. STABLE

If referencing regulations or standards, specify the version or date. The instruction should be evaluable the same way regardless of when it's read.

| Grade | Example | |-------|---------| | Pass | "Review the termination provisions under our internal policy [policy name and reference], dated December 12, 2024." | | Fail | "Follow latest market standards" (which standards? will change over time) |

Step 4: Grade the Signal

| Criteria Met | Action | |--------------|--------| | All 4 criteria pass | Add to skill directly | | Less than 4 criteria | Ask for clarification (see Step 5) |

Step 5: Ask for Clarification

When feedback doesn't meet all criteria, ask for what's missing using the AskUserQuestion tool:

I detected a correction but need more information to improve the skill.

You said: "[user's feedback]"

To create a clearer instruction, I need the following information: 

[Structured tool call listing what's missing based on failed criteria]

If the user provides clarification → Update the instruction and proceed to Step 6.

If the user prefers the original → Proceed to Step 6 with the original instruction.

Step 6: Propose Changes

--- Learning: [skill-name] ---

Proposed additions:

1. "[exact instruction to add]"
   Source: "[quote from conversation]"

2. "[exact instruction to add]"
   Source: "[quote from conversation]"

---

Apply these changes? [Y/n]

Step 7: If Approved

1. Update SKILL.md

   • Read skills/[skill-name]/SKILL.md
   • Add each instruction in the appropriate section
   • Each instruction must be readable and applicable on its own

2. Update skills/[skill-name]/CHANGELOG.md

   • Create if doesn't exist
   • Add new entry AT THE TOP:

     ## [DATE (format: "January 7, 2026")]
     [Description of changes in natural language, 1-3 sentences]
     

   • Entry rules:
     • Most recent at top
     • 1-3 sentences max
     • Natural language
     • No git references

Step 8: Save Observations

For signals that couldn't be processed, offer to save:

Save these observations for later review?
- "[signal 1]" - Status: [why insufficient]
- "[signal 2]" - Status: [why insufficient]

If yes, append to skills/[skill-name]/OBSERVATIONS.md

---

Secondary Commands

self-improve on

1. Run:

   rm -f ./.disabled
   

2. Reply: "Automatic mode enabled."

self-improve off

1. Run:

   touch ./.disabled
   

2. Reply: "Automatic mode disabled."

self-improve status

Check .disabled file existence and report.

self-improve [skill-name] history

1. Display CHANGELOG.md content
2. Ask: "Would you like to revert to a previous version?"
3. If yes:
   • update the appropriate sections in skills/[skill-name]/SKILL.md
   • update skills/[skill-name]/CHANGELOG.md with a rollback note

---

Examples

Example 1: All criteria met

User said: "Always flag non-compete clauses over 12 months as high risk"

Evaluation:

• Complete: Yes - instruction is fully specified
• Precise: Yes - "12 months" and "high risk" are clear
• Atomic: Yes - single check
• Stable: Yes - no time dependency

Result: Add directly

Example 2: Missing criteria

User said: "Flag any non-market-standard indemnification clause"

Evaluation:

• Complete: No - "non-market-standard" is not defined
• Precise: No - "market standard" is subjective and varies by deal type
• Atomic: Yes - single check
• Stable: No - market standards evolve over time

Action: Ask for clarification using the AskUserQuestion tool:

I detected a correction but need more details.

You said: "Flag any non-market-standard indemnification clause"

To make this actionable, can you specify:
- What makes an indemnification clause "non-market-standard"? (e.g., uncapped liability, coverage of indirect damages, no carve-outs for gross negligence)

Do you want to provide more details, or should I add the instruction as you stated it?

If user clarifies: Update the instruction and add it. If user prefers the original: Add the instruction as stated.

---

Important Notes

• Never guess what the user meant - always ask if unclear
• Never infer requirements from context - they must be explicit
• One instruction = one check - split bundled feedback
• Fewer good instructions is better than many vague ones
• CHANGELOG.md is the user-facing record