propose-skill-update

Files (1)

• SKILL.md

SKILL.md (first lines)

# Propose Skill Update

## Quick Reference

When you observe 3+ distinct occurrences of a pattern, propose a skill update. Only specific additions are allowed. Core process rewrites are never allowed. The user approves before any change.

## When to Use

- You've seen the same trigger condition 3+ times that isn't in a skill
- You've seen the same anti-pattern 3+ times that isn't documented
- A verification step was needed 3+ times that isn't in the checklist
- `compound-docs` has captured 3+ learnings about the same topic

## When NOT to Use

- Fewer than 3 distinct occurrences (one-offs aren't patterns)
- The update would rewrite a skill's core process
- The update adds project-specific details to a general skill
- You're unsure — wait for more evidence

## The Ratchet: What's Allowed

| Allowed | Must Cite 3+ Occurrences |
|---------|--------------------------|
| New trigger condition | "I've seen this trigger 3 times: [evidence]" |
| New anti-pattern | "This mistake has happened 3 times: [evidence]" |
| New verification step | "This check was needed 3 times: [evidence]" |

| Never Allowed | Reason |
|---------------|--------|
| Rewriting core process | Core processes are stable — propose a new skill instead |
| Removing steps | Removal requires explicit user decision, not automated ratchet |
| Adding project-specific details | Skills are general. Use `dojo.config.md` for project specifics. |
| Changing skill priority/gate status | Architecture decision, not an automated update |

## Core Process

### Step 1: Gather Evidence

Document the 3+ occurrences:

```
SKILL UPDATE PROPOSAL: <skill-name>

Type: new trigger | new anti-pattern | new verification step

Evidence:
1. [Date/context] — [what happened]
2. [Date/context] — [what happened]
3. [Date/context] — [what happened]

Proposed Addition:
[The exact text to add to the skill]

Location in Skill:
[Which section: triggers, Anti-Patterns table, or verification checklist]
```

### Step 2: Present to User

> "I've noticed [pattern] across 3 separate instances. I'd like to add it to the `<skill-name>` skill. Here's the proposal:"
>
> [Show the proposal]

### Step 3: Apply If Approved

If the user approves:
1. Edit the SKILL.md file with the addition
2. Update the frontmatter if a new trigger was added
3. Run `build-index.ts` to regenerate the index
4. Note the update in a learning (`compound-docs`)

## Anti-Patterns

| Anti-Pattern | Why It's Wrong |
|--------------|----------------|
| Proposing updates from 1-2 occurrences | Not enough evidence. Wait for 3. |
| Rewriting instead of appending | The ratchet only adds. It never rewrites. |
| Adding without user approval | Skills belong to the user. Always ask first. |
| Project-specific additions to general skills | Use config, not skill edits. |

## Chaining

None — this is a terminal skill.

From thesyntaxninja/syntaxninja-dojo, MIT.

More from thesyntaxninja/syntaxninja-dojo