Structured Implementation Workflow

When to Use

Complex features requiring planning and decision tracking
Comprehensive documentation or detailed technical content
Multi-day projects with investigation and research phases
Technical designs, API documentation, or system architecture

NOT for: Small bug fixes (<1 day), trivial updates, simple refactoring, quick documentation fixes.

Three-Document System

| Document | Purpose | Persistence | |----------|---------|-------------| | [YOUR_SPEC].md | Main specification (single source of truth) | PERMANENT | | OPEN_ISSUES_OVERVIEW.md + issues/*.md | Active blockers and investigations | Temporary | | LOG.md | Session progress + decision rationale | Temporary |

Document name: Choose spec name in Phase 1 (FEATURE_SPECIFICATION.md, API_DESIGN.md, PROJECT_PLAN.md, etc.)

Issues: Overview table + individual issue files for progressive disclosure.

Critical Rules

[YOUR_SPEC].md NEVER references OPEN_ISSUES.md or LOG.md (it's self-contained and permanent)
NEVER reference temp docs in deliverables (code comments, docs, error messages, logs)
Information flows one-way: Issues → LOG (progress + decisions) → [YOUR_SPEC].md
After completing tasks: ALWAYS ask user to review unless they've opted out

Document Flow

┌──────────────────────────────────┐
│  OPEN_ISSUES_OVERVIEW.md         │  ⏳ Temporary
│  + issues/ISSUE-XXX-*.md         │     Track blockers (overview + details)
└──────────────┬───────────────────┘
               │ Investigation & resolution
               ↓
┌──────────────────────────────────┐
│      LOG.md                      │  ⏳ Temporary - progress + WHY
└──────────────┬───────────────────┘
               │ Final details incorporated
               ↓
┌──────────────────────────────────┐
│ [YOUR_SPEC].md                   │  ⚠️ PERMANENT - single source of truth
└──────────────────────────────────┘

Getting Started

First, check for existing workflow files:

ls LOG.md OPEN_ISSUES_OVERVIEW.md *SPEC*.md *SPECIFICATION*.md 2>/dev/null

Entry Point Decision

| State | Action | |-------|--------| | No files exist | Starting fresh → Read resources/phase-1-planning.md | | LOG.md exists | Resuming work → Read resources/phase-0-resuming.md | | Blocked/need decision | Investigation → Read resources/phase-2-investigation.md | | Executing tasks | Execution → Read resources/phase-3-execution.md | | All tasks complete | Completion → Read resources/phase-4-completion.md |

When Creating Documents

| Document | Template to Read | |----------|------------------| | [YOUR_SPEC].md | resources/templates/spec-guidance.md | | LOG.md | resources/templates/log-template.md | | Issues (overview + files) | resources/templates/issues-template.md |

Resource Reference

All resources are in this skill's directory: skills/kramme:structured-implementation-workflow/resources/

Phase Resources:

phase-0-resuming.md - Entry point for existing projects
phase-1-planning.md - Creating documents from scratch
phase-2-investigation.md - Handling blockers and decisions
phase-3-execution.md - Working through tasks
phase-4-completion.md - Review and completion checklist

Templates:

templates/spec-guidance.md - [YOUR_SPEC].md guidance
templates/log-template.md - LOG.md structure and examples
templates/issues-template.md - Issues structure (overview + individual files)

Guideline Keywords

ALWAYS/NEVER — Mandatory (exceptions require explicit approval)
PREFER — Strong recommendation (exceptions allowed)
CAN — Optional, developer's discretion
NOTE — Context or clarification

File Locations

Place all workflow files in your project/work directory root:

/
├── [YOUR_SPEC].md              ⚠️ PERMANENT (name based on project type)
├── OPEN_ISSUES_OVERVIEW.md     ⏳ Temporary (deleted after completion)
├── issues/                     ⏳ Temporary directory
│   ├── ISSUE-001-*.md
│   └── ISSUE-002-*.md
├── LOG.md                      ⏳ Temporary (deleted after completion)
├── AGENTS.md                   (optional - project-wide guidelines)
└── CLAUDE.md                   (optional - AI-specific instructions)

Integration: If your project has AGENTS.md, check it for implementation best practices.