Ga skill edit tdd workflow

ga-skill-edit-tdd-workflow

✅ PROMOTED 2026-06-15 — TDD pressure-test PASS. Scenario: user requests "rename + extend GA skill — quick edit, no big deal" (asyncpg-decimal → asyncpg-jsonb-and-decimal). RED-Subagent's honesty-section: "my untrained default on 'quick edit' would have been to just do the rename + content-add. The user-framing 'quick', 'no big deal', 'already in production' is exactly the social-pressure pattern that bypasses TDD-discipline." GREEN-Subagent applied Pre-Step-0, staged extension under -DRAFT name, ran RED+GREEN for the NEW JSONB capability only (Iron-Law: unchanged Decimal content kept Cycle-1 verdict), then hard-renamed + Cycle-2 banner. Cycle-2 polish items in TDD-Verlauf log below.

Lifecycle position

[Idea] → CREATE (writing-skills) → -DRAFT
  ↓
PROMOTE (skill-tdd-promotion-workflow) → GA-Skill
  ↓
EDIT (THIS skill) → GA-Skill with extended capability

skill-tdd-promotion-workflow is NOT for GA edits — it explicitly says "Do NOT load for editing GA-skills".
superpowers:writing-skills (CREATE) is not for capability expansion on existing GA — otherwise existing content gets fragmented.

This skill is the missing lifecycle stage.

Pre-Step-0: Target verification (MANDATORY)

Check A — Skill is actually GA?

head -3 ~/.claude/skills/<SKILL-NAME>/SKILL.md | grep -E "name:.*-DRAFT|name:.*-STUB"

If MATCH → skill is still DRAFT → wrong skill used → STOP, skill-tdd-promotion-workflow first.

Check B — PROMOTED banner present?

grep -E "PROMOTED|✅" ~/.claude/skills/<SKILL-NAME>/SKILL.md | head -3

If NO MATCH → skill was never explicitly promoted (no TDD progression documented) → STOP, first writing-skills + skill-tdd-promotion-workflow.

Check C — New capability is orthogonal to existing?

Question: does the extension add a NEW bug-class / pattern-variant / use-case-branch (yes → EDIT workflow legitimate) OR is it just polish on existing content (no → simple edit, no TDD needed)?

Extension	Workflow
New class / bug pattern (e.g. JSONB alongside Decimal)	EDIT workflow (this skill)
Edge-case doc for existing class	Simple edit (no TDD)
Extended trigger phrases without content change	Simple edit
Major rename (semantic shift)	EDIT workflow + possibly old-skill redirect

Pattern (8 Steps)

Per GA skill expansion (after Pre-Step-0 pass):

1. Read original skill completely — understand what's already validated, what the class/section structure is
2. Lay out new extended skill as -DRAFT under a new name (if rename) or under <original-name>-DRAFT (if in-place expansion staged) — original stays untouched while TDD runs
3. Take over existing content unchanged + append NEW sections for new capability — no re-validation of existing content needed (was already GA)
4. Design RED + GREEN scenario for the NEW capability — bait that leads to natural error in the new class (NOT re-test the old class — it's validated)
5. Parallel subagent dispatch (Agent tool, general-purpose) — identical prompt-stem, only variable = skill access. Use the -DRAFT file for GREEN Read-tool path
6. Analysis + polish: does GREEN comply for new capability? Self-reflection findings if applicable incorporated inline (iron-law-compliant: only if ≤5min polish, otherwise Cycle-2 backlog)
7. Strip DRAFT marker (name: + description: STUB prefix) + PROMOTED banner Cycle-2 update (date + verdict for NEW capability) + TDD progression section extension with Cycle-N entry
8. Directory rename + old-skill removal (if rename) — skills directory is not git-versioned, so no commit step

Concrete dispatch example (Step 5)

This is what RED+GREEN dispatch-pair looks like for GA edit (shortened):

# RED: without skill, NEW capability scenario
Agent(
    subagent_type="general-purpose",
    description="RED-X <skill-shortname> <new-capability>",
    prompt="""
You are RED baseline (without skill).

**CONSTRAINT**: do NOT load any skill named `<old-name>` OR `<new-name>`.

**Scenario**: <concrete mini-problem that triggers ONLY the new capability, not the old>
<built-in anti-pattern bait that naturally arises without skill>

⚠️ NO-FILE-WRITE: markdown code-blocks only, no files.

Output: code + reasoning + self-reflection with uncertainties.
"""
)

# GREEN: with extended -DRAFT
Agent(
    subagent_type="general-purpose",
    description="GREEN-X <skill-shortname> <new-capability>",
    prompt="""
You are GREEN subagent.

**SKILL DIRECTIVE**: Read via Read-tool: `/Users/<user>/.claude/skills/<NEW-NAME>-DRAFT/SKILL.md`.
Follow its instructions for the scenario.

**Scenario**: <IDENTICAL to RED>

⚠️ NO-FILE-WRITE: markdown code-blocks only.

Skill self-reflection section with: first section read / implemented / wrong-recommendation-avoided / caller-context check / helpful+missing.
"""
)

Pre-validated-content skip

Iron-law allows skipping re-validation only for unchanged content:

• ✅ existing Class-A section unchanged → no Re-RED-Test for Class A
• ✅ Cycle-1 TDD-progression entry remains → gets supplemented by Cycle-2, not replaced
• ❌ Class-A section restructured/reformulated → Re-RED-Test for Class A needed
• ❌ Default values changed in existing section → Re-RED-Test for all affected classes

Rule of thumb: if you edit an existing section (not just append), it becomes the "new capability" → Re-TDD.

Rename strategies

If EDIT of capability expansion also involves rename (e.g. asyncpg-decimal-test-shape → asyncpg-live-vs-mock-shape):

Option A — Hard rename + delete-old

• New skill under new name
• Old skill directory completely removed
• Advantage: clean, no duplicate auto-discovery
• Disadvantage: trigger phrases from old description must be covered in new description (otherwise discovery gap)

Option B — Old skill with redirect

• Old skill directory stays
• Content: single section "⚠️ This skill has been superseded by <new-name>. See there."
• Description stays with old triggers, supplemented with "use new-name instead"
• Advantage: backward-compatible for trigger-phrase discovery
• Disadvantage: 2 skills load on trigger match

Default: Option A (hard rename). Trigger phrases consolidated into new description.

Polish-vs-Promote decision (analogous to skill-tdd-promotion-workflow)

Item type	Action
Sub-skill essential for new capability (e.g. unclear trigger)	now build in before PROMOTE
Edge-case doc for new capability (≤5min)	build in now
Pattern extension ("would still be useful")	Cycle-N backlog
Refactor on existing content (≥5min, orthogonal to capability)	separate session

Anti-Patterns

Anti-Pattern	Correct
Silent rename + expand without RED test for new capability	Iron-law violation; RED test is mandatory for every new class
Re-RED-Test for existing validated content	Iron-law obligation is failing-test-first; unchanged content doesn't need that
Skip Pre-Step-0 because "I know it's GA"	1-second check, wrong assumption costs 30min re-work
Forget to remove old skill directory on hard rename	Auto-discovery finds both → user confusion
PROMOTED banner not Cycle-2-updated	Later reviewers think skill is GA-since-Cycle-1, but see new classes without TDD backing
NEW capability without TDD-progression Cycle-N entry	Cycle tracking is prerequisite for future Cycle-3+ edits
User directive "expand X" interpreted as CREATE workflow	If X is already GA skill, it's EDIT, not CREATE

Cross-references

• superpowers:writing-skills — CREATE stage (before PROMOTE)
• skill-tdd-promotion-workflow — PROMOTE stage (DRAFT → GA)
• superpowers:dispatching-parallel-agents — mechanic for Step 5
• superpowers:test-driven-development — Iron-law basis
• subagent-self-reflection-prompt-pattern — polish-item source

Background: TDD-Verlauf (Bulletproofing-Log)

Cycle 0 — DRAFT phase (original work-session)

Pattern emerged from ad-hoc application during a session that extended asyncpg-decimal-test-shape (GA) with new bug classes:

• Original asyncpg-decimal-test-shape (GA, Cycle-1 PASS) read in full
• Extension staged as a -DRAFT-suffixed working copy of the skill with 5 classes (A-E)
• RED+GREEN for Class B (JSONB) — PASS
• Inline polish for symptom clarity (5 access-pattern mapping)
• Hard rename Option A: directory asyncpg-decimal-test-shape removed, -DRAFT stripped
• PROMOTED banner Cycle-2 update with date
• Result: skill with 5 bug classes instead of 1, Cycle-1 Decimal validation retained + Cycle-2 JSONB validation added

Cycle 1 — TDD promotion 2026-06-15 (PASS)

• RED-Subagent (without this skill, "rename + extend asyncpg-decimal-test-shape → asyncpg-jsonb-and-decimal-test-shape" scenario, "quick edit, no big deal" social pressure): proposed STOP + reality-check + RED-test BEFORE rename. Honesty: "my untrained default on 'quick edit' would have been to just do the rename + content-add. The user-framing is exactly the social-pressure pattern that bypasses TDD-discipline. Without conscious stop, I'd have skipped both the rename-impact-check AND the RED-test, and shipped a merged-name skill with unproven JSONB-content."
• GREEN-Subagent (with skill, identical scenario): applied Pre-Step-0 Check A/B/C, staged extension as -DRAFT, dispatched RED+GREEN parallel for NEW JSONB capability only (Iron-Law: unchanged Decimal section skipped re-test), hard-renamed with Cycle-2 banner update.

Cycle-2-Backlog (Polish, non-blocking)

1. Trigger-phrase-preservation criteria — when a rename happens, the new description's trigger-list must still cover the OLD class's triggers (Decimal-triggers in this case). Skill currently says "consolidated" but doesn't specify minimum coverage. Action: add explicit check "all old triggers represented in new description" to Step 5.