Skill Tighten

Skill Tighten

Core responsibility: Fix language that causes agents to skip or underweight instructions. Not behavioral gaps — that is skill-review's job. Only phrasing: rationale prose, soft language, missing enforcement signals, redundant repetition.

Input: One or more of:

• A file path: source/atoms/clean-code/SKILL.md
• A skill name: clean-code (resolves to the correct path automatically)
• A tier: atoms (tightens all skills in that tier)
• No argument: tightens all skills across all tiers

Output: Edited files + a report per skill:

Copy code
## skill-tighten — {skill-name}
Lines: {before} → {after}
Changes:
1. {what changed} — {one-line reason}
2. ...
Result: TIGHTENED ({N} changes) | CLEAN (no changes needed)

How to verify this skill did its job:

• Every cut section had zero commands — only rationale
• Every softened phrase was "consider / think about / you may want to / it is recommended"
• Every added STOP: was on a hard rule that previously had no enforcement signal
• No rule, gate, checklist item, or branching logic was removed
• Re-running after edits returns CLEAN

Step 1: Read the skill

Read the full SKILL.md. Also read all sibling files: references/defaults.md, references/methodology-detail.md, assets/template.md, or any file referenced by a Read instruction in the skill body. For each <!-- include: {name} --> line, also read source/shared/{name}.md — tools/install.sh swaps it in at that spot.

Do not edit yet — complete the full audit first.

Step 2: Apply the tighten checklist

For each item, scan the entire file. Mark every instance found — do not stop at the first.

T1 — Non-actionable sections

Sections that explain why the skill exists, describe the problem, or narrate context without issuing a single command. Cut the entire section. Preserve the pointer to a referenced file if one exists.

Patterns that always qualify:

• Section titled "Core Principle", "Purpose", "Problem", "Background", "Why This Matters", "How It Is Used", "Integration with Other Skills"
• Opening paragraph before a numbered list that restates what the numbered list will do
• Closing paragraph after a gate that explains what happens if the gate were skipped

Pass: Section contains at least one imperative instruction (do, read, write, verify, check, apply, stop, flag). Fail: Section contains only declarative statements, rationale, or scope commentary.

T2 — Soft language

Words and phrases that agents treat as optional:

Pass: Instruction is an imperative verb with no hedging qualifier. Fail: Instruction contains any of the patterns above.

T3 — Missing STOP: gates

Hard rules that must not be skipped — gates on advancing to next steps, checklist preambles, non-negotiable constraints — stated as bold prose without a **STOP:** prefix.

Pass: Hard gate reads **STOP:** as the first token of its line or sentence. Fail: Hard gate is phrased as "Do NOT...", "Never...", "Always verify...", "Must not..." without the STOP: prefix.

Add **STOP:** prefix. Do not rewrite the instruction itself.

T4 — Redundant repetition

The same point stated twice in different words. Keep the sharper version; cut the other.

Patterns:

• Section heading restated in the section's opening sentence
• Instruction followed by a sentence explaining what the instruction means
• Rationale sentence after a clear gate ("Without this, X would happen")
• Same rule in two adjacent bullets

Pass: Each statement appears once in its sharpest form. Fail: Two sentences convey the same instruction or the same constraint.

T5 — Table column bloat

Columns whose content explains why a trigger exists, rather than being the trigger.

Common offenders: columns titled "Why", "Reason", "Rationale", "Because", "Notes" in a table whose other columns already encode the actionable information.

Pass: Every column in the table is actionable — the agent does something with it. Fail: A column contains only explanatory prose the agent reads but cannot act on.

Drop the column. Do not drop the row.

T6 — Trailing rationale sentences

Sentences appended to a clear instruction that explain why the instruction exists. The instruction is already sufficient — the explanation adds tokens without adding compliance.

Patterns:

• "Without this, agents will X"
• "This ensures that X"
• "This is because X"
• "X is important because Y"
• Any sentence beginning with "This" that follows a complete imperative

Pass: Instruction ends at the action. No trailing explanation. Fail: Instruction is followed by a sentence that begins with "This", "Without", "Because", or restates the consequence of not following the instruction.

Step 3: Make edits

Apply all findings. Edits in order of checklist item (T1 first, T6 last) — structural cuts before phrasing fixes.

Rules:

• Cut sections entirely when T1 applies — do not rephrase them
• Add **STOP:** as a prefix — do not rewrite the surrounding instruction
• Do not remove checklist items, branching logic, gates, or output format specifications
• Do not restructure sections — targeted cuts and additions only
• If a T1 section contains one buried imperative, extract that line and discard the section wrapper
• Text inside an include belongs to source/shared/{name}.md — edit it there, never inline it into one skill; the change reaches every skill that includes it.

Step 4: Report

After all edits:

Copy code
## skill-tighten — {skill-name}
Lines: {before} → {after} ({delta})
Files changed: SKILL.md [, defaults.md, ...]

Changes:
1. [T1] Cut "{section name}" — no commands, pure rationale
2. [T3] Added STOP: to "{rule}" — was bold prose, now enforced gate
3. [T5] Dropped "Reason" column from {table name} — rationale, not instruction
...

Result: TIGHTENED ({N} changes)

If no changes needed:

Copy code
Result: CLEAN — no language compliance issues found