abildtoft/kramme:siw:continue

Structured Implementation Workflow (SIW)

A local, markdown-based workflow for planning, tracking, and implementing multi-step work without external services.

What This Skill Does

This skill is the SIW entry point. When invoked, it:

1. Detects current state — checks for siw/LOG.md, siw/OPEN_ISSUES_OVERVIEW.md, and the spec document.
2. Resumes if state exists — follows the resume flow in references/phase-0-resuming.md (read LOG.md "Current Progress", check open issues, continue the next task).
3. Routes if not — points to the right SIW subcommand based on what's needed (see Working With Existing Files below).

It does not directly create, modify, or close SIW documents; that is delegated to the SIW subcommands listed in the Commands Reference table.

When to Use

• Resuming SIW work — primary auto-trigger when siw/LOG.md is present.
• Starting structured work on a complex feature, multi-issue project, or technical design.
• Local-only tracking when an external tracker (Linear, Jira) is not in use.

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

Issue Naming

Issues use prefix-based numbering:

• G-XXX — General issues (standalone, non-phase)
• P1-XXX, P2-XXX, etc. — Phase-specific issues

Workflow 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/DISCOVERY_BRIEF.md | Greenfield discovery output before siw:init creates the full workflow | Temporary | | siw/SPEC_STRENGTHENING_PLAN.md | Refinement discovery output waiting for review or --apply | Temporary | | siw/AUDIT_IMPLEMENTATION_REPORT.md | Spec compliance audit findings from /kramme:siw:implementation-audit | Temporary | | siw/AUDIT_SPEC_REPORT.md | Spec quality audit findings from /kramme:siw:spec-audit | Temporary | | 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:issue-define        │  Create general work items (G-XXX)
│  /kramme:siw:generate-phases     │  Create phase-based issues (P1-XXX, P2-XXX)
│  → siw/issues/ISSUE-{prefix}-XXX-*.md │
└──────────────┬───────────────────┘
               │ Implementation
               ↓
┌──────────────────────────────────┐
│  /kramme:siw:issue-implement     │  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

1. Spec NEVER references temp docs - It's self-contained and permanent
2. NEVER reference temp docs in code - Comments, docs, error messages must not mention siw/LOG.md or siw/issues
3. Decisions flow one-way: Issues → siw/LOG.md → siw/[YOUR_SPEC].md
4. Sync before completion: Before closing an issue, migrate the issue's decisions from siw/LOG.md into the permanent spec (the spec sync step inside /kramme:siw:issue-implement)

---

Commands Reference

| Command | Purpose | | --- | --- | | /kramme:siw:init | Initialize SIW documents (spec, siw/LOG.md, siw/issues) | | /kramme:siw:discovery | Deep discovery interview — works pre-spec (greenfield) or on existing specs (strengthening). Probes until 95% confident about actual wants. | | /kramme:siw:issue-define | Define a new work item with guided interview (creates G-XXX issues) | | /kramme:siw:generate-phases | Break spec into atomic phase-based issues (P1-XXX, P2-XXX, G-XXX) | | /kramme:siw:issue-implement | Start implementing a defined issue (accepts G-001, P1-001, etc.) | | /kramme:siw:product-audit | Product critique of specs/plans — evaluates target user, problem/solution fit, user state modeling, and scope correctness | | /kramme:siw:spec-audit | Audit spec quality (coherence, completeness, clarity, scope, actionability, testability, value proposition, technical design) before implementation | | /kramme:siw:implementation-audit | Audit codebase against spec for discrepancies, naming misalignments, and missing implementations | | /kramme:siw:resolve-audit | Resolve audit findings one-by-one with executive summaries, alternatives, and SIW issue creation. Add --auto to let the model choose each resolution without pausing for confirmation. If both audit reports exist, pass the report path to keep the run scoped. | | /kramme:siw:issue-reindex | Remove DONE issues and renumber remaining within each prefix group | | /kramme:siw:reset | Reset workflow state (migrate log to spec, clear issues) | | /kramme:siw:close | Close SIW project, generate docs in docs/<feature>/, remove temporary files | | /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/AUDIT_IMPLEMENTATION_REPORT.md siw/AUDIT_SPEC_REPORT.md siw/SPEC_STRENGTHENING_PLAN.md siw/DISCOVERY_BRIEF.md siw/*SPEC*.md siw/*SPECIFICATION*.md siw/*PLAN*.md siw/*DESIGN*.md siw/issues/ 2> /dev/null

Entry Point Decision

| State | Action | | --- | --- | | No files exist | Run /kramme:siw:init to set up | | Discovery brief exists, but no spec yet | Run /kramme:siw:init siw/DISCOVERY_BRIEF.md to turn the brief into a full SIW workflow | | Discovery brief + strengthening plan, but no spec yet | Review siw/SPEC_STRENGTHENING_PLAN.md, fold accepted changes into siw/DISCOVERY_BRIEF.md, then archive/remove the plan before running /kramme:siw:init siw/DISCOVERY_BRIEF.md. Or run /kramme:siw:init to discard the plan and continue from the brief | | Spec-strengthening plan exists without a spec | Review or archive the plan first, or run /kramme:siw:init to decide whether to discard it before starting fresh | | Files exist, resuming | Read siw/LOG.md "Current Progress" section first | | Spec feels weak or underspecified | Run /kramme:siw:discovery to probe what you actually want and strengthen the spec | | Starting a new project, want to think it through | Run /kramme:siw:discovery in greenfield mode before creating any spec | | Need new work item | Run /kramme:siw:issue-define | | Ready to implement | Run /kramme:siw:issue-implement {number} | | Spec written, want product validation | Run /kramme:siw:product-audit to evaluate product thinking before implementation | | Spec written, not yet validated | Run /kramme:siw:spec-audit to check spec quality before implementing | | Implementation done | Run /kramme:siw:implementation-audit to verify spec compliance | | Audit report ready | Run /kramme:siw:resolve-audit to triage findings and create issues one-by-one, or add --auto for a non-interactive pass. If both audit reports exist, pass the report path to avoid resolving both. | | Iteration complete | Run /kramme:siw:reset to start fresh | | Project complete, want docs | Run /kramme:siw:close to generate documentation and clean up | | Project complete | Run /kramme:siw:remove to clean up |

Resuming Work

When existing SIW files are detected, follow the targeted reading flow in references/phase-0-resuming.md. In short: read the "Current Progress" section of siw/LOG.md, scan siw/OPEN_ISSUES_OVERVIEW.md for status, then either continue the IN PROGRESS issue or pick up the next READY one with /kramme:siw:issue-implement.

---

Issue Lifecycle

                                            ┌─────────────────────────────┐
                                            │   (shortcut when confident) │
                                            ▼                             │
┌─────────┐          ┌─────────┐        ┌─────────┐          ┌─────────┐  │
│  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 (use when the resolution is uncertain or needs sign-off)
• DONE — Resolved and documented (skip IN REVIEW when the resolution is straightforward and confident)

When an issue is completed:

1. Resolution steps documented in the issue file's ## Resolution section
2. Decisions logged in siw/LOG.md
3. Key decisions synced to the permanent spec (the spec sync step in /kramme:siw:issue-implement)
4. Status set to IN REVIEW (uncertain solution) or DONE (confident solution)
5. Row updated in 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
│   ├── AUDIT_IMPLEMENTATION_REPORT.md            ⏳ Temporary (audit output)
│   ├── AUDIT_SPEC_REPORT.md            ⏳ Temporary (audit output)
│   ├── DISCOVERY_BRIEF.md              ⏳ Temporary (greenfield discovery output)
│   ├── SPEC_STRENGTHENING_PLAN.md      ⏳ Temporary (refinement handoff artifact)
│   ├── OPEN_ISSUES_OVERVIEW.md     ⏳ Temporary
│   ├── issues/                     ⏳ Temporary directory
│   │   ├── ISSUE-G-001-setup.md        # General issues
│   │   ├── ISSUE-G-002-docs.md
│   │   ├── ISSUE-P1-001-feature-a.md   # Phase 1 issues
│   │   ├── ISSUE-P1-002-feature-b.md
│   │   └── ISSUE-P2-001-bug-fix.md     # Phase 2 issues
│   └── LOG.md                      ⏳ Temporary

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 the templates in this skill's assets/ directory:

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

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

---

Phase Resources

For detailed guidance on specific phases, read:

| Phase | Resource | | ---------------------- | ------------------------------------- | | Resuming existing work | references/phase-0-resuming.md | | Planning from scratch | references/phase-1-planning.md | | Handling blockers | references/phase-2-investigation.md | | Executing tasks | references/phase-3-execution.md | | Completing work | references/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