T-ELV7-prototype-skill-refine-skill

Status: closed/superseded · Impact: medium · Complexity: medium

Goal

Skills under apps/sdlc/skills/ are accumulating multi-paragraph prose for operations that should be in code. The motivating case is task-work Step 4 (42 lines of prose for git worktree add + an executor call), but the pattern repeats — long, English-encoded determinism where an op would be shorter, testable, and harder for the LLM to skip or paraphrase. There is no tooling to help an author identify a Step worth extracting or perform the extraction systematically. This task builds a narrow first-cut /skill-refine skill that operationalises one operation: extract a single prose Step into an op-backed call, informed by an explicit set of skill-authoring principles. Step 4 of task-work is the canonical first target.

Today

Location	Role today
`apps/sdlc/skills/task-work/SKILL.md`	Carries 42 lines of prose under `## 4. Create the worktree` for what is essentially `git worktree add` + an executor call. Verifies the pattern that motivates this skill.
`apps/sdlc/skills/`	35+ skills, most with multi-paragraph Steps mixing orchestration prose with deterministic operations. No tooling to identify or extract the deterministic parts.
`apps/sdlc/conventions/`	Holds project-wide conventions (branch-naming, commit-messages, sdlc-yaml, etc.). Skill phrasing/structure rules live in `apps/sdlc/skills/CLAUDE.md` per S-0006-skill-md-is-direct-instruction, but no doc states the extraction principle “deterministic operations belong in ops, prose belongs in SKILL.md”.
`apps/sdlc/lib/`	The established home for shared modules and registry ops (D-H7FS-op-substrate-surface). Steps already extracted live here as `sdlc` verbs — `entities validate` (frontmatter validation), `task parse-touchpoints`, `gate skill-prose`, `quality baseline` — exemplars for the target shape.
`~/.claude/skills/new-skill/`	The user’s existing skill-creation workflow (user-level, outside the repo). Sibling to skill-refine but distinct in purpose: new-skill creates a skill from scratch; skill-refine improves an existing one.

Proposed

A new skill at apps/sdlc/skills/skill-refine/ whose single operation is: given a SKILL.md path and a Step heading, propose and (on operator OK) execute an extraction of the Step’s deterministic parts into a registry op. The skill is grounded in a written apps/sdlc/conventions/skill-authoring.md that captures the principles (deterministic operations → ops; orchestration and judgment → prose; one-place-only for shared logic; etc.).

Concretely the skill:

Reads the named Step from the SKILL.md (e.g. ## 4. Create the worktree).
Identifies the deterministic substeps within the prose — shell commands, script invocations, file I/O, branch-naming rules.
Proposes an extraction: target op (a defineOp registry op under apps/sdlc/lib/, surfaced as an sdlc <path…> verb per D-H7FS-op-substrate-surface), signature, what arguments the skill passes, exit-code contract.
After operator OK (via AskUserQuestion), generates the op, generates a one-line replacement for the Step body, and updates SKILL.md.
Validates the resulting SKILL.md still passes the skill-prose lint (sdlc gate skill-prose).
Surfaces what was kept as prose vs what was extracted so the operator can sanity-check.

The skill is deliberately narrow. It does not:

Identify candidate Steps automatically across all skills (that’s a follow-up).
Refactor multiple Steps in one invocation.
Move logic across skills (that’s a skill-consolidate skill, also a follow-up).
Generate new tests for the extracted op (the operator decides — though the skill can suggest a fixture shape).

Step 4 of task-work is the canonical first user. The actual refactor lands as a separate task (T-33C0-refactor-task-work-step-4-via-skill-refine) that depends on this one and explicitly cites “performed via /skill-refine.”

Approach

Survey existing extractions on main — entities validate, task parse-touchpoints, gate skill-prose, quality baseline — to characterise what a “clean” extraction looks like. Note shape (TS/Bun defineOp registry op with zod-typed input/output, exit-code contract, stdout marker conventions, surfaced as an sdlc <path…> verb).
Write apps/sdlc/conventions/skill-authoring.md — the principles the skill enforces. At minimum: deterministic operations → registry op (testable, exit codes); orchestration and judgment → prose (LLM-tractable, AskUserQuestion calls); shared logic lives in one place (apps/sdlc/lib/); SKILL.md cites ops, ops never cite SKILL.md.
Author apps/sdlc/skills/skill-refine/SKILL.md — usage /skill-refine <SKILL.md path> "<Step heading>". Walk through: read Step → identify deterministic ops → propose extraction → confirm → execute → validate. Keep prose lean; this skill is the canonical example of “don’t write what you’d ask skill-refine to extract.”
Co-locate any deterministic helpers the skill needs under apps/sdlc/skills/skill-refine/. Likely a small parser that takes a SKILL.md body + heading and yields the Step’s bounded section text; can grow into a proper extractor over time.
Use Step 4 of task-work as the dogfood test. Run skill-refine end-to-end against it (in a worktree, manually for the prototype). Confirm the resulting extraction (e.g. an sdlc task setup-worktree verb) is correct and the new SKILL.md prose is shorter and still passes sdlc gate skill-prose.
Document the skill at docs/skills/skill-refine.md per the established skill-doc shape (flowchart, when-to-use, what-it-does, links to principles).

Files to touch

Location	Kind	Change
`apps/sdlc/skills/skill-refine/SKILL.md`	new	The skill prose.
`apps/sdlc/skills/skill-refine/tests/`	new	Eval-harness shape; at minimum a fixture proving the skill cleanly extracts a known Step.
`apps/sdlc/conventions/skill-authoring.md`	new	The written principles the skill enforces.
`docs/skills/skill-refine.md`	new	User-facing skill doc with flowchart.

Acceptance criteria

AC-1: apps/sdlc/conventions/skill-authoring.md exists and articulates at minimum: (a) deterministic operations belong in registry ops / sdlc verbs; (b) orchestration and judgment belong in SKILL.md prose; (c) shared logic lives in exactly one place; (d) SKILL.md cites ops, ops never cite SKILL.md.
AC-2: Invoking /skill-refine <SKILL.md path> "<Step heading>" against a well-formed Step that contains deterministic operations produces a concrete extraction proposal naming the target op path, signature, and exit-code contract — before any file is modified.
AC-3: After operator OK, the skill generates the op, rewrites the Step body, and the resulting SKILL.md passes sdlc gate skill-prose.
AC-4: The skill exits cleanly with no side effects if the operator declines the proposal at the AskUserQuestion gate.
AC-5: docs/skills/skill-refine.md exists with a flowchart and is reachable from the skills index.

Out of scope

Automatic candidate identification across all skills (a future skill-refine --scan mode).
Refactoring Step 4 itself. That happens in T-33C0-refactor-task-work-step-4-via-skill-refine, which depends on this task.
Generating new tests for the extracted op (the operator writes them).
Moving logic across skills (future skill-consolidate operation).

Dependencies

none

Discovery context

Spawned 2026-05-28 during an audit of open/ready tasks. The Step 4 worktree-init prose (42 lines of orchestration English for what’s really git worktree add + an executor call) made the pattern visible: skills accumulate prose for deterministic operations because there’s no tooling to help authors notice or extract them. The applies_when: predicate task originally tried to fix this surface-level (mark the Step as conditional) but the underlying issue is the Step is mostly script-shaped. A /skill-refine skill grounded in explicit principles is the structural fix.

← Back to Tasks