version: "1.0.1" name: do-work description: "Autonomous work execution on STV-traced scenarios. Selects unfinished scenarios from trace.md, implements via stv:work, loops until done or user input needed."

Do Work — STV Autonomous Execution

Overview

do-work automates the complete STV implementation workflow: select unfinished trace scenarios → implement via stv:work → quality gates → loop until done.

Core principle: Scan trace.md for ready scenarios → Bundle into work chunks → Execute with stv:work → Commit → Repeat.

Sizing Rubric (expected code change, added + deleted)

When to Use

Use when:

• trace.md with unfinished scenarios exists
• Ready for autonomous implementation execution
• User wants minimal interruption until work is done

Do NOT use when:

• No trace.md exists (use stv:new-task first)
• User asked a single specific question
• Exploring/researching without implementation

Workflow Phases

Phase A: Task Selection
    ↓
Phase B: STV Work Execution (→ stv:work)
    ↓
Phase C: Context Check
    ↓
Phase D: Loop Decision
    ↓ (loop back to A or stop)

Phase A: Task Selection (~5min)

Goal: Select unfinished scenarios from trace.md and bundle for execution.

1. Scan trace files

• Glob for docs/*/trace.md across the project
• Read each trace.md's Implementation Status table
• Collect scenarios where Status != "Complete"

1. Extract File Map (MANDATORY)

• For each trace.md, extract ALL unique file paths from:
• Section 3c "Persisted files" — backtick-quoted paths under - Persisted files:
• Section 4 "Side Effects" — paths after UPDATE:, INSERT:, DELETE:
• Deduplicate across all scenarios → File Map Checklist
• This is the real completion checklist. Tests are a subset; File Map is the whole.

1. Prioritize scenarios

• Respect dependency order (earlier scenarios first)
• Integration-first tiebreaker: among scenarios at the same dependency level, prioritize those whose File Map entries include existing files with 200+ lines. These core pipeline files are the work most likely to be deferred — do them first.
• Group by feature if multiple features have ready scenarios
• Estimate combined size tier

1. Bundle scenarios (target: xlarge)

• Bundle related scenarios into work chunks
• If total < large: include more related scenarios
• If total > xlarge: split into multiple bundles, execute first bundle
• Cap at xlarge per bundle

1. Present bundle to user

## Work Bundle
 
### Target: {feature-name}
Trace: docs/{feature}/trace.md
 
### Scenarios to implement:
| # | Scenario | Size | Dependencies |
|---|----------|------|-------------|
| {n} | {title} | {tier} | {deps or "none"} |
 
### File Map (all files trace says to modify):
| # | File | Scenarios | Modified? |
|---|------|-----------|-----------|
| 1 | {path} | {scenario numbers} | pending |
 
Estimated total: {tier}
 
Proceed? (or adjust bundle)

Phase B: STV Work Execution

Goal: Implement the bundled scenarios using stv:work.

Skill(skill="stv:work") invoked

• stv:work performs per-scenario GREEN + Trace Verify
• After completion, update trace.md Implementation Status

After stv:work completes:

1. File Map Completion Gate (MANDATORY — before quality gates)

For each file in the File Map Checklist:

• Check: was this file modified? (git diff --name-only)
• Mark as: modified / NOT modified

IF any File Map file is NOT modified:

• List unmodified files with their trace scenario references
• For each unmodified file:

a. Re-read the trace scenario(s) that reference this file b. Determine what change was required c. Implement the missing change d. Re-run tests

• Re-check File Map. Do NOT proceed until all files are modified.

★ Tests GREEN alone is NOT sufficient. File Map 100% = the real completion gate.

1. Gap Detection Gate (before quality gates)

• Re-read spec.md for the feature
• Compare ALL implemented code against spec requirements
• Check 5 gap types: assumption_injection, scope_creep, direction_drift, missing_core, over_engineering
• If gap detected:
• Log gap and attempt autonomous correction (1st attempt)
• Re-run stv:work verify after correction
• If gap persists → stop and report to user (Phase D)

1. Quality Gates

``bash # Run project-specific commands npm test # or bun test / pytest / dotnet test npm run build # if applicable npm run lint # if applicable ``

1. Spec Re-verification (MANDATORY — before commit)

Re-read the spec.md referenced in trace.md. For each acceptance criterion in the spec:

• Is it covered by a test?
• Is it covered by trace Section 4 side effects?
• Is it implemented in code even if no test covers it?

IF any spec requirement is not implemented: → Implement it now, re-run quality gates.

1. Commit & Push

• Commit with detailed message referencing trace scenarios
• Push to remote

Phase C: Context Check (~1min)

Goal: Prevent context overflow.

IF context > 70%:
  1. Save critical state (current trace progress)
  2. Use /compact or context compression
  3. OR end session gracefully with resume point
 
ELSE:
  Continue to Phase D

Phase D: Loop Decision (~1min)

Goal: Decide whether to continue autonomous work.

Continue to Phase A if:

• More unfinished scenarios exist in trace.md
• All requirements understood
• No blockers
• Context budget OK

Stop and report to user if:

• All scenarios complete (feature done)
• Requirements unclear or ambiguous
• Architectural decision needed (switching cost >= medium, can't use generic pattern)
• Context near limit
• Major milestone reached
• Gap detected and autonomous correction failed (2nd gap = escalate)

Report format when stopping:

## Work Session Report
 
### Completed
-{N}/{total} scenarios GREEN + Verified
-Feature: {feature-name}
 
### Remaining
-{M} scenarios still pending
-Next: Scenario {n} — {title}
 
### Quality
-Tests: {pass}/{total} passing
-Build: clean / {N} errors
-Lint: clean / {N} warnings
 
### Next Step
→ Run `stv:do-work` to continue
→ Or `stv:work docs/{feature}/trace.md` for specific trace

Mid-Implementation Decision Thresholds

During execution, unexpected architectural decisions may arise.

Default thresholds: auto_decide <= small (~20 lines), must_ask >= medium (~50 lines)

for each unexpected decision:
  if switching_cost <= small:
    → Autonomous decision + record in Auto-Decision Log
    → If small tier, report result to user
  elif switching_cost >= medium:
    → Check if switching cost can be reduced via generic architecture
      → If reducible: autonomous decision + log
      → If not reducible: move to Phase D and ask the user

Auto-Decision Log format: See decision-gate.md for the full template. Minimum fields: Decision, switching cost tier, Rationale, Impact if changed.

Integration with Other Skills

INVOKES:

• stv:work — Per-scenario implementation execution in Phase B

CALLED BY:

• stv:what-we-have-to-work — After bundle selection
• stv:what-to-work — After routing

PRECONDITIONS:

• docs/{feature}/trace.md must exist
• trace.md must have unfinished scenarios
• If not → guide to stv:new-task

Common Mistakes

Anti-Patterns — Known Failure Modes

★ Parts assembled without wiring do not work. Assembly is not optional — it is the feature.

NEVER

• Start implementation without trace.md
• Skip quality gates
• Skip gap detection gate (runs BEFORE quality gates)
• Ignore context management
• Skip logging autonomous decisions
• Attempt more than 1 autonomous gap correction per bundle (escalate on 2nd)
• Declare work complete when File Map has unmodified files
• Skip Spec Re-verification before commit
• Treat test coverage as equivalent to spec coverage