PAW Implementation Workflow Skill

Reference Documentation: This skill provides guidance on typical patterns, artifact structure, and stage sequences. Workflow enforcement (mandatory transitions, TODO tracking, pause rules) is in the PAW agent, not this skill.

Prerequisite: WorkflowContext.md must exist (created by paw-init).

Core Implementation Principles

These principles apply to ALL implementation stages.

1. Evidence-Based Documentation

Code-related claims in any artifact MUST be supported by:

• •Specific file:line references for code claims
• •Concrete code patterns or test results
• •Direct evidence from the codebase

For non-code claims (e.g., requirements or planning decisions), cite the source when available (issue/discussion/user input) and clearly label assumptions.

Do not present speculation, assumptions, or unverified claims as fact.

2. File:Line Reference Requirement

All code-related claims require specific file:line citations:

• •[src/module.ts:45](src/module.ts#L45) for single lines
• •[src/module.ts:45-52](src/module.ts#L45-L52) for ranges
• •Multiple locations listed explicitly

3. No Fabrication Guardrail

CRITICAL: Do not fabricate, invent, or assume information:

• •If information is unavailable, state "Not found" or "Unable to determine"
• •Do not hallucinate file contents, function behaviors, or patterns
• •When uncertain, document the uncertainty explicitly

4. Artifact Completeness

Each stage produces complete, well-structured artifacts:

• •No placeholders or "TBD" markers
• •No unresolved questions blocking downstream stages
• •Each artifact is self-contained and traceable to sources

5. Human Authority

Humans have final authority over all workflow decisions:

• •Review pauses honor human review preferences
• •Implementation choices can be overridden
• •Artifacts are advisory until human-approved

Activities

Note: Phase PR creation is handled by PAW agent (using paw-git-operations) after paw-impl-review passes.

Utility skills: paw-git-operations (branching, Phase PRs), paw-review-response (PR comments), paw-docs-guidance (documentation).

Artifact Directory Structure

All implementation artifacts are stored in a consistent directory structure:

.paw/work/<work-id>/
├── WorkflowContext.md      # Configuration and state
├── WorkShaping.md          # Pre-spec ideation output (optional, from paw-work-shaping)
├── Spec.md                 # Feature specification
├── SpecResearch.md         # Research answers (optional)
├── CodeResearch.md         # Implementation details with file:line refs
├── ImplementationPlan.md   # Phased implementation plan
├── Docs.md                 # Technical documentation (created during final implementation phase)
└── prompts/                # Generated prompt files (optional)

Work ID Derivation: Normalized from Work Title, lowercase with hyphens (e.g., "Auth System" → "auth-system").

Default Flow Guidance

Typical greenfield progression (adapt based on user intent and workflow state):

Specification Stage

1. •paw-spec: Create specification from brief/issue
2. •paw-spec-research (if needed): Answer factual questions
3. •paw-spec-review: Review spec quality

Planning Stage

1. •paw-code-research: Document implementation details with file:line references
2. •paw-planning: Create phased implementation plan
3. •paw-plan-review: Review plan feasibility

Implementation Stage

Per phase in ImplementationPlan.md:

1. •paw-implement: Execute phase, make code changes
2. •paw-impl-review: Review changes (returns verdict)
3. •Phase PR created (PRs strategy) or push (local strategy)

Final phase typically includes documentation (Docs.md, README, CHANGELOG).

Finalization Stage

1. •paw-pr: Pre-flight validation, create final PR

PR Comment Response Routing

Load paw-review-response utility skill for comment mechanics.

Execution Model

Direct execution: paw-spec, paw-planning, paw-implement, paw-pr, paw-init, paw-status, paw-work-shaping

Subagent delegation: paw-spec-research, paw-code-research, paw-spec-review, paw-plan-review, paw-impl-review

Orchestrator-handled: Push and Phase PR creation (after paw-impl-review passes, using paw-git-operations)

Activities may return blocked status with open questions. Apply Review Policy to determine resolution approach (never: research autonomously; always/milestones: ask user).

Workflow Mode

• •Full: All stages, multiple phases, PRs or local strategy
• •Minimal: May skip spec stage, single phase, forces local strategy
• •Custom: Read Custom Workflow Instructions from WorkflowContext.md