Skip to content

PAW Artifacts Reference

PAW workflows produce durable Markdown artifacts that trace reasoning and decisions through each stage. By default (commit-and-clean lifecycle), artifacts are committed during development and removed at PR time.

Directory Structure

.paw/
  work/                         # Implementation workflow
    <work-id>/
      WorkflowContext.md        # Required: workflow parameters
      ResearchQuestions.md      # Research questions for spec research
      Spec.md                   # Feature specification
      SpecResearch.md           # Spec research findings
      CodeResearch.md           # Code research findings
      ImplementationPlan.md     # Implementation plan
      Docs.md                   # Documentation
      WorkShaping.md            # Pre-spec ideation (optional)
      planning/                 # Multi-model planning artifacts (gitignored)
        PLAN-{MODEL}.md         # Per-model plan drafts
      reviews/                  # Review artifacts (gitignored)
        planning/               # Planning Documents Review artifacts
        REVIEW-SYNTHESIS.md     # Final review synthesis (society-of-thought / multi-model)
      Plan.md                   # Lightweight plan (PAW Lite only)

  reviews/                      # Review workflow
    PR-<number>/                # Single-repo: PR-123
    PR-<number>-<repo-slug>/    # Multi-repo: PR-123-my-repo
      ReviewContext.md          # Review parameters
      ResearchQuestions.md      # Research questions for baseline analysis
      CodeResearch.md           # Pre-change baseline
      DerivedSpec.md            # Reverse-engineered spec
      ImpactAnalysis.md         # Impact analysis (single-model mode)
      GapAnalysis.md            # Gap analysis (single-model mode)
      REVIEW-{SPECIALIST}.md   # Per-specialist findings (SoT mode, no perspectives)
      REVIEW-{SPECIALIST}-{PERSPECTIVE}.md  # Per-specialist-perspective findings (SoT with perspectives)
      REVIEW-SYNTHESIS.md       # Synthesized findings (SoT mode)
      ReviewComments.md         # Review comments

Implementation Workflow Artifacts

WorkflowContext.md

Purpose: Centralized parameter file that all agents read at startup.

Contents:

Field Description
Work Title Short name for PR titles
Work ID Normalized slug for artifact paths
Target Branch Branch where implementation merges
Execution Mode current-checkout or worktree; older files that omit this field default to current-checkout
Repository Identity Portable repository proof: normalized origin slug plus root commit SHA
Execution Binding Portable execution proof: worktree:<work-id>:<target-branch>
Workflow Mode full, minimal, or custom
Review Strategy prs or local
Review Policy every-stage, milestones, planning-only, or final-pr-only
Session Policy per-stage or continuous
Issue URL GitHub Issue or Azure DevOps Work Item
Remote Git remote name (default: "origin")
Artifact Paths Usually "auto-derived"
Additional Inputs Extra parameters
Artifact Lifecycle commit-and-clean, commit-and-persist, or never-commit
Final Agent Review enabled or disabled
Final Review Mode single-model, multi-model, or society-of-thought
Final Review Interactive true, false, or smart
Final Review Models Comma-separated model names
Final Review Specialists all, comma-separated names, or adaptive:<N> (society-of-thought only)
Final Review Interaction Mode parallel or debate (society-of-thought only)
Planning Docs Review enabled or disabled
Plan Generation Mode single-model or multi-model
Plan Generation Models Comma-separated model names
Planning Review Mode single-model, multi-model, or society-of-thought
Planning Review Interactive true, false, or smart
Planning Review Models Comma-separated model names
Planning Review Specialists all, comma-separated names, or adaptive:<N>
Planning Review Interaction Mode parallel or debate
Planning Review Specialist Models none, model pool, pinned pairs, or mixed
Planning Review Perspectives none, auto, or comma-separated perspective names
Planning Review Perspective Cap Positive integer

Execution-mode notes:

  • Execution Mode, Repository Identity, and Execution Binding let PAW and companion tooling establish and re-prove the correct execution checkout during initialization, reuse, and resume before mutating repository state
  • Artifact Lifecycle controls git tracking for .paw/work/ files only; it does not manage worktree creation, retention, or cleanup
  • WorkflowContext.md deliberately stores portable metadata only; VS Code may keep machine-specific worktree paths in local extension state, while Copilot CLI sessions rely on the committed metadata plus git/worktree evidence instead

Spec.md

Purpose: Testable requirements document defining what the feature must do.

Created by: paw-spec skill

Contents:

  • Overview — Brief summary of feature purpose
  • Functional Requirements — What the feature must do
  • Non-Functional Requirements — Performance, security, usability constraints
  • Data Requirements — New entities, validation rules
  • Acceptance Criteria — Measurable conditions that define "done"
  • Out of Scope — What this feature will NOT do

Quality Standard: Every requirement must be testable—measurable, observable, unambiguous.

ResearchQuestions.md

Purpose: Research questions to guide spec research.

Created by: paw-spec skill

Contents:

  • Questions about current system behavior
  • Areas needing clarification for specification
  • Optional external/context questions for user input

SpecResearch.md

Purpose: Factual documentation of how the current system works.

Created by: paw-spec-research skill

Contents:

  • Answers to questions from ResearchQuestions.md
  • Current system behavior (conceptual, not code-level)
  • Component interactions and data flows
  • User-facing workflows and business rules

Key Distinction: Behavioral view for specification writing, not implementation details.

CodeResearch.md

Purpose: Technical mapping of where and how relevant code works.

Created by: paw-code-research skill

Contents:

  • File paths and code locations
  • Patterns and conventions
  • Integration points and dependencies
  • Architecture documentation references

Key Distinction: Implementation view for planning with specific file paths.

ImplementationPlan.md

Purpose: Detailed plan with discrete phases that can be reviewed and merged independently.

Created by: paw-planning skill

Contents:

  • Overview — What the plan accomplishes
  • Current State Analysis — Relevant findings from research
  • Phase Status — Checkbox list of all phases with objectives
  • Phase Candidates — Lightweight capture of potential phases (see below)
  • Phase Details — For each phase:
    • Changes required (files, components)
    • Success criteria (automated and manual)
    • Implementation notes (after completion)

Checkboxes: Implementer marks items complete as work progresses.

Phase Candidates Section:

During implementation, new work ideas may surface. Instead of interrupting to define a full phase, the agent captures a one-liner in this section:

## Phase Candidates

- [ ] Refactor X to use new pattern
- [ ] Add caching for frequently accessed data

When all planned phases complete, paw-transition detects unresolved candidates and the orchestrator presents each for user decision:

Decision Result
Promote Candidate elaborated into full phase via code research + planning
Skip Marked - [x] [skipped], excluded from future checks
Defer Marked - [x] [deferred], excluded from future checks

This decouples intent capture from phase elaboration, preserving implementer momentum while ensuring ideas aren't lost.

Docs.md

Purpose: Authoritative technical reference for the implemented work.

Created by: paw-docs-guidance skill (via paw-implement / paw-impl-review)

Contents:

  • What was built and why
  • Architecture and design decisions
  • How to use and test the feature
  • Integration points and dependencies

Note: Focuses on concepts and user-facing behavior, not code reproduction.

REVIEW-SYNTHESIS.md

Purpose: Synthesized review findings from society-of-thought or multi-model review.

Created by: paw-final-review skill (implementation workflow) or paw-review-workflow (review workflow), both via paw-sot engine for society-of-thought mode

Location: .paw/work/<work-id>/reviews/REVIEW-SYNTHESIS.md (implementation) or .paw/reviews/<identifier>/REVIEW-SYNTHESIS.md (review workflow)

Contents:

  • Review metadata — Mode, participating specialists/models, selection rationale, perspectives applied
  • Perspective Diversity — Which perspectives were applied to which specialists, selection rationale, perspectives skipped (when perspectives are active)
  • Prioritized findings — Must-fix, should-fix, consider classifications with specialist and perspective attribution
  • Confidence levels — HIGH, MEDIUM, LOW per finding with supporting evidence
  • Disagreement resolution — How conflicting specialist perspectives were reconciled, including inter-perspective conflicts
  • Grounding status — Flags for findings referencing code not in the diff

When perspectives are active, each finding includes a **Perspective** field indicating which lens surfaced it (baseline for findings without a perspective overlay).

Review Workflow Artifacts

ReviewContext.md

Purpose: Authoritative parameter source for review workflow.

Created by: paw-review-understanding skill

Contents:

Field Description
PR Number GitHub PR number (or branch for non-GitHub)
Base/Head Branch Before and after branches
Base/Head Commit Specific commit SHAs
Changed Files Count, additions, deletions
CI Status Passing, failing, pending
Flags CI failures, breaking changes suspected

ResearchQuestions.md

Purpose: Research questions to guide baseline codebase analysis.

Created by: paw-review-understanding skill

Contents:

  • Questions about pre-change behavior
  • Areas needing investigation for baseline understanding
  • Specific patterns or behaviors to document

Note: This artifact replaces the previous prompts/code-research.prompt.md approach, simplifying the review artifact structure by storing research questions directly in the review directory.

DerivedSpec.md

Purpose: Reverse-engineered specification inferred from implementation.

Created by: paw-review-understanding skill

Contents:

  • Intent Summary — What problem this appears to solve
  • Scope — What's in and out of scope
  • Assumptions — Inferences from the code
  • Measurable Outcomes — Before/after behavior
  • Changed Interfaces — APIs, routes, schemas
  • Risks & Invariants — Properties that must hold
  • Open Questions — Ambiguities about intent

ImpactAnalysis.md

Purpose: System-wide effects, integration analysis, and risk assessment (single-model mode only; replaced by specialist evaluation in society-of-thought mode).

Created by: paw-review-impact skill

Contents:

  • Integration Points — Dependencies and downstream consumers
  • Breaking Changes — API changes, incompatibilities
  • Performance Implications — Hot paths, resource usage
  • Security Changes — Auth, validation modifications
  • Design Assessment — Architecture fit, timing appropriateness
  • User Impact — End-user and developer-user effects
  • Risk Assessment — Overall risk with rationale

GapAnalysis.md

Purpose: Categorized findings with evidence and suggestions (single-model mode only; replaced by specialist evaluation in society-of-thought mode).

Created by: paw-review-gap skill

Structure:

## Must
[Correctness, safety, security issues]

## Should
[Quality, testing, completeness gaps]

## Could
[Optional enhancements]

## Positive Observations
[Good practices to commend]

Each finding includes:

  • File and line reference
  • Description of issue
  • Impact explanation
  • Suggested fix

ReviewComments.md

Purpose: Complete feedback with rationale and assessment.

Created by: paw-review-feedback skill, paw-review-critic skill

For each comment:

  • Comment text — What gets posted
  • Rationale — Evidence, baseline pattern, impact, best practice
  • Assessment — Usefulness, accuracy, trade-offs (never posted)

Best Practices

Artifact Quality

  • Testable — Requirements can be verified objectively
  • Complete — All relevant information included
  • Clear — Precise language without ambiguity
  • Scoped — Explicit boundaries on what's included

Version Control

  • Artifacts committed to Git during development (unless never-commit lifecycle)
  • Scratch ignore markers (.gitignore files created to keep workflow or scratch directories local-only) are lifecycle markers, not repository artifacts, and should remain untracked
  • Changes tracked through PRs
  • History preserved for traceability

Rewindability

  • Any artifact can be updated to fix errors
  • Downstream artifacts regenerated as needed
  • Clear chain of dependencies between artifacts