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/contracts/*.md | Contract specifications referenced by issues or specs | 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/PRODUCT_AUDIT.md | Product audit findings from /kramme:siw:product-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 90% 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 more than one audit report exists (spec, implementation, product), 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/PRODUCT_AUDIT.md siw/SIW_*.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

Synced SIW spec-exclusion contract (keep aligned across SIW spec detectors): LOG.md, OPEN_ISSUES_OVERVIEW.md, DISCOVERY_BRIEF.md, SPEC_STRENGTHENING_PLAN.md, AUDIT_*.md, PRODUCT_AUDIT.md, SIW_*.md.

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 (report-path guidance in the Commands Reference above). | | 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
│   ├── contracts/                  ⚠️ PERMANENT (optional, linked contracts)
│   │   └── 01-api-contract.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