Structured Implementation Workflow (SIW)

A local issue tracking system using markdown files to plan, track, and document implementations without requiring external services.

When to Use

Complex features requiring planning and decision tracking
Multi-issue projects with multiple work items
Projects without Linear or when you want local-only tracking
Technical designs, API documentation, or system architecture

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

Quick Start

/kramme:siw:init                    # Initialize workflow documents
/kramme:siw:define-issue "feature"  # Create a work item
/kramme:siw:implement-issue 001     # Start implementing
/kramme:siw:restart-issues          # Remove DONE issues, renumber from 001
/kramme:siw:reset                   # Reset for next iteration (keeps spec)
/kramme:siw:remove                  # Clean up when done

Three-Document System

| Document | Purpose | Persistence | |----------|---------|-------------| | siw/[YOUR_SPEC].md | Main specification (single source of truth) | PERMANENT | | siw/supporting-specs/*.md | Detailed specifications by domain | PERMANENT | | siw/OPEN_ISSUES_OVERVIEW.md + siw/issues/*.md | Work items to implement | Temporary | | siw/LOG.md | Session progress + decision rationale | Temporary |

What Each Document Contains

Specification (PERMANENT):

Project overview and objectives
Scope (in/out)
Design decisions (migrated from siw/LOG.md)
Success criteria

Supporting Specs (PERMANENT, optional):

Detailed specifications organized by domain
Examples: data model, API design, UI specs, user stories
Named with ordering prefix: 00-overview.md, 01-data-model.md, etc.
Main spec references these via TOC

Issues (TEMPORARY):

Individual work items (features, bugs, improvements)
Each issue has: problem, context, scope, acceptance criteria
Deleted when implemented

siw/LOG.md (TEMPORARY):

Current progress and status
Decision log with rationale
Session continuity between conversations

Document Flow

┌──────────────────────────────────┐
│  /kramme:siw:define-issue        │  Create work items
│  → siw/issues/ISSUE-XXX-*.md     │
└──────────────┬───────────────────┘
               │ Implementation
               ↓
┌──────────────────────────────────┐
│  /kramme:siw:implement-issue     │  Work on issues
│  → siw/LOG.md (progress + decisions) │
└──────────────┬───────────────────┘
               │ Decisions migrated
               ↓
┌──────────────────────────────────┐
│  siw/[YOUR_SPEC].md              │  ⚠️ PERMANENT - single source of truth
│  (updated via sync step)         │
└──────────────────────────────────┘

Critical Rules

Spec NEVER references temp docs - It's self-contained and permanent
NEVER reference temp docs in code - Comments, docs, error messages must not mention siw/LOG.md or siw/issues
Decisions flow one-way: Issues → siw/LOG.md → siw/[YOUR_SPEC].md
Sync before completion: Always run Step 10 (Spec Sync) in implement-issue

Commands Reference

| Command | Purpose | |---------|---------| | /kramme:siw:init | Initialize SIW documents (spec, siw/LOG.md, siw/issues) | | /kramme:siw:define-issue | Define a new work item with guided interview | | /kramme:siw:implement-issue | Start implementing a defined issue | | /kramme:siw:restart-issues | Remove DONE issues and renumber remaining from 001 | | /kramme:siw:reset | Reset workflow state (migrate log to spec, clear issues) | | /kramme:siw:remove | Clean up all SIW files after completion |

Working With Existing Files

When SIW files already exist, check the current state:

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

Entry Point Decision

| State | Action | |-------|--------| | No files exist | Run /kramme:siw:init to set up | | Files exist, resuming | Read siw/LOG.md "Current Progress" section first | | Need new work item | Run /kramme:siw:define-issue | | Ready to implement | Run /kramme:siw:implement-issue {number} | | Iteration complete | Run /kramme:siw:reset to start fresh | | Project complete | Run /kramme:siw:remove to clean up |

Resuming Work

When resuming a session with existing SIW files:

Read siw/LOG.md first - Check "Current Progress" section for:
- What was last completed
- What's next
- Any blockers
Check siw/OPEN_ISSUES_OVERVIEW.md - See which issues are:
- READY (not started)
- IN PROGRESS (being worked on)
- IN REVIEW (awaiting review/approval)
- DONE (completed)
Continue or start new - Either:
- Continue the in-progress issue
- Pick up the next ready issue with /kramme:siw:implement-issue

Issue Lifecycle

Created              In Progress           Review              Completed
   │                      │                   │                    │
   ▼                      ▼                   ▼                    ▼
┌─────────┐          ┌─────────┐        ┌─────────┐          ┌─────────┐
│  READY  │ ───────► │IN PROG  │ ─────► │IN REVIEW│ ───────► │  DONE   │
└─────────┘          └─────────┘        └─────────┘          └─────────┘

Issue States:

READY - Defined, waiting to be picked up
IN PROGRESS - Currently being implemented
IN REVIEW - Work complete, awaiting review/approval
DONE - Finalized (issue file deleted or marked complete)

When an issue is completed:

Decisions are logged in siw/LOG.md
Key decisions are synced to spec (Step 10)
Issue file is deleted
Row removed from siw/OPEN_ISSUES_OVERVIEW.md

File Locations

All workflow files live in the siw/ folder in the project root:

/
├── siw/
│   ├── [YOUR_SPEC].md              ⚠️ PERMANENT (name chosen at init)
│   ├── supporting-specs/           ⚠️ PERMANENT (optional, for large projects)
│   │   ├── 00-overview.md
│   │   ├── 01-data-model.md
│   │   ├── 02-api-specification.md
│   │   └── 03-ui-specification.md
│   ├── OPEN_ISSUES_OVERVIEW.md     ⏳ Temporary
│   ├── issues/                     ⏳ Temporary directory
│   │   ├── ISSUE-001-feature-a.md
│   │   └── ISSUE-002-bug-fix.md
│   └── LOG.md                      ⏳ Temporary
├── AGENTS.md                       (optional)
└── CLAUDE.md                       (optional)

When to Use Supporting Specs

Use siw/supporting-specs/ when:

Main spec exceeds ~500 lines
Multiple distinct domains (data model, API, UI, user stories)
Different team members own different sections
You want targeted reading during execution

Naming convention: NN-descriptor.md (e.g., 01-data-model.md, 02a-cms-ui.md)

Templates Reference

When manually creating documents, use these templates from: skills/kramme:structured-implementation-workflow/resources/templates/

| Document | Template | |----------|----------| | siw/[YOUR_SPEC].md | templates/spec-guidance.md | | siw/LOG.md | templates/log-template.md | | siw/issues | templates/issues-template.md |

Tip: Using /kramme:siw:init and /kramme:siw:define-issue is preferred over manual creation.

Phase Resources

For detailed guidance on specific phases, read:

| Phase | Resource | |-------|----------| | Resuming existing work | resources/phase-0-resuming.md | | Planning from scratch | resources/phase-1-planning.md | | Handling blockers | resources/phase-2-investigation.md | | Executing tasks | resources/phase-3-execution.md | | Completing work | resources/phase-4-completion.md |

Guideline Keywords

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