do-work

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)

Tier	Lines	Example
tiny	~5	Config values, constants, string literals
small	~20	One function, one file, local refactor
medium	~50	Multiple files, interface changes
large	~100	Cross-cutting concerns, schema migrations
xlarge	~500	Architecture shift, framework replacement

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"

2. 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.

3. 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

4. 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

5. 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:

0. 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)

2. Quality Gates

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

3. 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.

4. 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

Mistake	Fix
Attempting execution without trace	Check docs/*/trace.md first
Ignoring bundle size	Target xlarge, cap at xlarge
Skipping quality gates	Run test/build/lint every time
Context overflow	Respond at 70% threshold in Phase C
Stopping for trivial decisions	switching cost <= small → autonomous decision
File Map files not all modified	Run File Map Completion Gate before quality gates

Anti-Patterns — Known Failure Modes

Anti-Pattern	Symptom	Fix
"Test pass = done" bias	All tests GREEN but integration code not wired, config not updated	File Map Gate + Spec Re-verification catch the gap between "tests pass" and "feature works"
File Map as decoration	trace lists 5 files, only 3 modified — files without tests skipped	Extract File Map in Phase A, gate on it in Phase B. Every Section 3c/4 file MUST show a diff
Complexity avoidance	New utility files created but 500-line core pipeline file untouched	Integration-first ordering. Large existing files get priority. The wiring IS the feature

★ 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