5.3 KiB

Raw Blame History

State Handoff Patterns

How to pass state between workflow steps without relying on conversation context.

Why File-Based State

Problem	File-Based Solution
Context compaction loses history	Files persist
Forked skills have no conversation access	Files are accessible
State scattered across messages	Single source of truth
Hard to audit what happened	Artifacts are reviewable

Core Pattern

Skill A writes → artifacts/step-a.md
                        ↓
Skill B reads artifacts/step-a.md → writes artifacts/step-b.md
                                            ↓
Skill C reads artifacts/step-b.md → ...

Each skill:

Reads previous artifact(s)
Does its work
Writes its own artifact
Updates context.md with decisions

Artifact Structure

Standard Header

# {Step Name}: {Brief Description}

**Generated**: {timestamp}
**Input**: artifacts/{previous-step}.md
**Status**: complete | partial | blocked

---

Sections by Step Type

Triage/Analysis artifacts:

## Problem Statement
{clear definition}

## Scope
- Files: {list}
- Modules: {list}

## Findings
{what was discovered}

## Risks
- {risk 1}
- {risk 2}

## Next Steps
- [ ] {action 1}
- [ ] {action 2}

Plan artifacts:

## Goal
{what we're trying to achieve}

## Approach
{chosen approach with rationale}

## Task Breakdown
1. {task 1}
2. {task 2}
3. {task 3}

## Test Plan
- [ ] {test 1}
- [ ] {test 2}

## Rollback Plan
{how to undo if needed}

Review artifacts:

## Summary
{brief assessment}

## Findings
| Severity | Issue | Location | Recommendation |
|----------|-------|----------|----------------|
| {sev} | {desc} | {loc} | {rec} |

## Concerns
- {concern 1}
- {concern 2}

## Approval
- [ ] Ready to proceed
- [ ] Needs revision

Test artifacts:

## Commands Run
```bash
{command 1}
{command 2}

Results

Suite	Pass	Fail	Skip
{name}	{n}	{n}	{n}

Failures

{test name}

Error: {message}
Fix: {resolution}

Coverage

{coverage summary}


## context.md Pattern

The shared context.md tracks living state across all steps:

```markdown
# Current Context

## Task
{what we're working on}

## Decisions Made
- {decision 1} — {rationale}
- {decision 2} — {rationale}

## Current Focus
{what step we're on, what's next}

## Blockers
- {blocker if any}

## Open Questions
- {question if any}

---
Last updated: {timestamp}

Update Pattern

Each skill appends to decisions and updates current focus:

## Decisions Made
- {existing decisions}
- Chose X over Y for {reason} — from /plan  ← NEW

constraints.md Pattern

Static project constraints, rarely changed:

# Project Constraints

## Security
- No secrets in code
- All inputs validated
- {project-specific rules}

## Style
- {linting rules}
- {naming conventions}

## Performance
- {latency budgets}
- {size limits}

## Testing
- {coverage requirements}
- {required test types}

Gates Between Steps

Use artifact existence as gates:

---
name: ship
---

# Prerequisites

Check these artifacts exist and show success:
- artifacts/test-report.md: all tests passing
- artifacts/review-notes.md: no blocking issues
- artifacts/preflight.md: all checks green

If any missing or failing, do not proceed.

Gate Validation Patterns

# In skill body:

Before proceeding, verify:
1. artifacts/plan.md exists
2. All tasks in plan.md are checked off
3. artifacts/test-report.md shows no failures

If any check fails:
- Report what's missing
- Do not proceed
- Suggest next step

Parallel Workflow Branches

When workflow branches, use namespaced artifacts:

artifacts/
  triage.md
  plan.md
  security/
    audit.md
    review.md
  performance/
    profile.md
    review.md
  final-review.md  ← merges both branches

Merge Pattern

---
name: final-review
---

Read and merge:
- artifacts/security/review.md
- artifacts/performance/review.md

Synthesize into artifacts/final-review.md with:
- Combined findings
- Priority ranking
- Unified recommendation

Failure Recovery

When a step fails, artifacts capture state for recovery:

# artifacts/implement.md

## Status: blocked

## Completed
- [x] Task 1
- [x] Task 2

## Blocked On
- Task 3: {error message}

## Recovery Steps
1. {fix suggestion}
2. Retry /implement

## Context Preserved
- Last working state at commit abc123
- Rollback with: git checkout abc123

Tips

Keep Artifacts Focused

One purpose per artifact. If an artifact does multiple things, split it.

Include Timestamps

**Generated**: 2026-01-26T10:30:00Z

Helps track freshness and debugging.

Link to Source

## Findings
Issue in `src/auth/login.ts:42` — missing validation

Specific file:line references for easy navigation.

Self-Contained

Each artifact should be understandable without reading others:

# Review: Authentication Refactor

**Context**: Refactoring auth module to use JWT (from artifacts/plan.md)

## Scope Reviewed
- src/auth/*.ts
- src/middleware/auth.ts

Version Artifacts When Needed

artifacts/
  plan-v1.md
  plan-v2.md  ← after revision
  plan-final.md

Or use git to track history and keep single files.

5.3 KiB Raw Blame History