alchemiststudiosdotai/execute-phase

Execute Phase

Overview

Execute implementation plans from .artifacts/plan/ with strict discipline: gated checks, atomic commits, and a single living execution log.

North Star Rule

Follow the plan exactly. Do not improvise. Do not fix what isn't in the plan.

If something is ambiguous or missing, stop and ask the user.

When to Use

• User provides a plan path in .artifacts/plan/
• User says "execute this plan" or "run the plan"
• User references a plan document for implementation

What This Skill Does NOT Do

| ❌ DON'T | ✅ DO INSTEAD | |---------|--------------| | Re-plan the work | Execute tasks as written | | Fix unrelated issues | Follow plan scope only | | Skip quality gates | Run all gates, document failures | | Ignore the plan | Plan is the source of truth |

Execute Phase Workflow

0. Input

User provides: $ARGUMENTS = path to plan in .artifacts/plan/

1. Read Plan & Lock Context

Read the FULL plan. Extract:

• Milestones
• Task IDs and order
• Acceptance tests
• Quality gates
• Success criteria

2. Pre-Flight Snapshot

Before any code changes:

# Capture git state
BRANCH=$(git branch --show-current)
SHA=$(git rev-parse --short HEAD)
STATUS=$(git status --short)

Create rollback point:

git add -A
git commit -m "rollback: before executing plan <topic>"

Create .artifacts/execute/YYYY-MM-DD_HH-MM-SS_<topic>.md:

---
title: "<topic> execution log"
link: "<topic>-execute"
type: debug_history
ontological_relations:
  - relates_to: [[<plan-link>]]
tags: [execute, <topic>]
uuid: "<uuid>"
created_at: "<ISO-8601 timestamp>"
owner: "{{user}}"
plan_path: ".artifacts/plan/<file>.md"
start_commit: "<short_sha>"
env: {target: "local|staging|prod", notes: ""}
---

## Pre-Flight Checks
- Branch: <branch>
- Rollback commit: <sha>
- DoR satisfied: yes/no
- Access/secrets: present/missing
- Fixtures/data: ready/not ready

[If any NO → abort and add Blockers section]

3. Task-by-Task Execution

For EACH task in plan order:

1. Read task requirements
2. Implement minimal slice aligned with acceptance test
3. Run local validation
4. Commit atomic change with Task ID in message
5. Update execution log

Commit message format:

T<NNN>: <task summary>

<brief description of change>

Refs: plan/<file>.md

4. Quality Gates

Run gates in order. Document ALL results.

Gate C - Code Quality

# Run tests
pytest

# Type check
mypy src/

# Lint
black --check src/

# Coverage
coverage report

Document in the execution log:

### Gate Results
- Tests: pass/fail + evidence
- Coverage: X% (target Y%)
- Type checks: pass/fail
- Linters: pass/fail

If gate FAILS:

• Record failure + remediation attempted
• STOP and ask user for next steps
• Do NOT roll back without user confirmation

5. Permalinks & Artifacts

If commits pushed:

# Get repo info for permalinks
gh repo view --json owner,name

Attach permalinks to:

• PRs/commits
• Build logs
• Coverage reports
• Security scans

Persist artifact pointers in the execution log.

6. Post-Deploy Verification (if applicable)

### Post-Deploy Verification
- Error rates: <metrics>
- Latencies: <metrics>
- Dashboard links: <URLs>
- Smoke/E2E results: <pass/fail>

Execution Log Template

Keep ONE document. Update as you work.

---
title: "<topic> execution log"
link: "<topic>-execute"
type: debug_history
ontological_relations:
  - relates_to: [[<plan-link>]]
tags: [execute, <topic>]
uuid: "<uuid>"
created_at: "<ISO-8601 timestamp>"
plan_path: ".artifacts/plan/<file>.md"
start_commit: "<sha>"
end_commit: "<sha>"
env: {target: "...", notes: "..."}
---

## Pre-Flight Checks
- Branch: <branch>
- Rollback: <commit_sha>
- DoR: satisfied/not
- Ready: yes/no

## Task Execution

### T001 – <Summary>
- Status: completed/skipped/failed
- Commit: <sha>
- Files: <list>
- Commands: <cmd> → <output>
- Tests: pass/fail
- Coverage delta: +X%
- Notes: <decisions made>

### T002 – <Summary>
[... repeat for each task ...]

## Gate Results
- Tests: X/Y passed
- Coverage: X% (target Y%)
- Type checks: pass/fail
- Security: # issues
- Linters: pass/fail

## Deployment (if applicable)
- Staging: success/fail
- Prod: success/fail
- Timestamps: <start> → <end>

## Issues & Resolutions
- T<NNN> – <issue> → <resolution|rollback|asked user>

## Success Criteria
- [ ] All planned gates passed
- [ ] Rollout completed or rolled back
- [ ] KPIs/SLOs within thresholds
- [ ] Execution log saved

## Next Steps
- Follow-ups, tech debt, docs

Final Report

After the Execute phase, summarize:

# Execution Report – <topic>

**Date:** {{date}}
**Plan:** <plan_file>
**Log:** <log_file>

## Overview
- Environment: <env>
- Start: <sha>
- End: <sha>
- Duration: Xh Ym
- Branch: <branch>

## Outcomes
- Tasks attempted: N
- Tasks completed: N
- Final status: Success | Failure | Blocked

## Gate Results
- Tests: pass/fail
- Coverage: X% (target Y%)
- Type checks: pass/fail
- Security: # issues

## What Was Touched
[List all files modified]

## Next Steps
- [ ] Item 1
- [ ] Item 2

Strict Rules

1. ONE execution log - Create once, update as you work. Do not create multiple docs.
2. Atomic commits - One commit per task. Task ID in commit message.
3. Rollback first - Create rollback commit before any code changes.
4. Gates are mandatory - Run all gates. Document failures. Stop on failure.
5. Plan is source of truth - Do not add, remove, or change tasks.
6. Ask when blocked - If gates fail or plan is ambiguous, stop and ask.

Validation Questions

Before proceeding with each task:

1. Clarity: Do I understand exactly what this task requires?
2. Scope: Is this within the plan's scope?
3. Dependencies: Are prerequisite tasks completed?
4. Rollback: Can I revert to the safe state?

Output Format

Start:

Executing plan: .artifacts/plan/<file>.md
Branch: <branch>
Rollback point: <commit_sha>
Tasks: N
Milestones: M

End:

Execution complete: Success | Failure | Blocked
Tasks completed: N/N
Log: .artifacts/execute/<file>.md
Next step: QA from execute using the generated execution log path

Handoff

After writing the execution log to .artifacts/execute/, proceed to qa-from-execute if the next step is the QA phase.