abildtoft/kramme:siw:issues-reindex

<!-- TODO: Refactor to <500 lines by moving Step 4: Verify Spec Capture of DONE Issues to references/ -->

Restart Issues

Remove all DONE issues and renumber remaining issues within each prefix group. This command:

1. Identifies all issues with status DONE
2. Verifies DONE issue decisions and LOG.md entries are captured in specs before deletion
3. Deletes DONE issue files
4. Renumbers remaining issues sequentially within each prefix group (G-, P1-, P2-, etc.)
5. Updates siw/OPEN_ISSUES_OVERVIEW.md with new numbers
6. Updates siw/LOG.md issue references to match new numbers

Use this when you want to clean up completed issues and have fresh numbering sequences within each group.

Important: Issues are renumbered within their own prefix group. Phase groupings remain intact.

Workflow

/kramme:siw:issues-reindex
    |
    v
[Find SIW files] -> Not found? -> Show error, abort
    |
    v
[Parse siw/OPEN_ISSUES_OVERVIEW.md] -> Extract all issues with statuses
    |
    v
[Identify DONE issues] -> List for deletion
    |
    v
[Identify remaining issues] -> Calculate new numbers per prefix group
    |
    v
[Confirm with user] -> Show what will happen
    |
    v
[Verify spec capture] -> Check DONE issues + LOG.md entries against specs
    |
    v
[Delete DONE issue files]
    |
    v
[Rename remaining issue files] -> Renumber within each prefix (G-003 -> G-001, P1-004 -> P1-002)
    |
    v
[Update siw/OPEN_ISSUES_OVERVIEW.md] -> New numbers, remove DONE rows
    |
    v
[Update siw/LOG.md] -> Update issue references to new numbers
    |
    v
[Report results]

---

Step 1: Find and Validate SIW Files

Check for required SIW files:

ls siw/OPEN_ISSUES_OVERVIEW.md siw/issues/ 2>/dev/null

If siw/OPEN_ISSUES_OVERVIEW.md doesn't exist:

No siw/OPEN_ISSUES_OVERVIEW.md found. Nothing to restart.

To initialize a new SIW workflow, run /kramme:siw:init

Action: Abort.

If siw/issues/ directory doesn't exist or is empty:

No issues found. Nothing to restart.

To create issues, run /kramme:siw:issue-define

Action: Abort.

---

Step 2: Parse Issues Overview

Read siw/OPEN_ISSUES_OVERVIEW.md section-by-section and extract all issues from the table.

For each section, extract:

• Section header
• Table schema (| # | Title | Status | Size | Priority | Mode | Related |, pre-Mode 6-column, or the legacy 5-column form)
• Any section-level metadata line immediately above the table (for example **Parallelization:** ...)

For each row, extract:

• Issue prefix and number (e.g., G-001, P1-002)
• Title
• Status (READY, IN PROGRESS, IN REVIEW, DONE)
• Size when present in the 6- or 7-column schema
• Priority
• Mode when present in the 7-column schema (AUTO or HITL)
• Related tasks

Categorize issues by prefix group:

• DONE issues per group: Will be deleted
• Active issues per group: Will be renumbered within their prefix (READY, IN PROGRESS, IN REVIEW)

Example grouping:

• G-001 (DONE), G-002 (READY), G-003 (READY) → Delete G-001, renumber G-002→G-001, G-003→G-002
• P1-001 (READY), P1-002 (DONE) → Delete P1-002, P1-001 stays as P1-001

---

Step 3: Determine Scope and Confirm

3.1 Ask About Scope (if phase issues exist)

If any phase issues (P1-, P2-, etc.) exist, ask which issues to include:

Use AskUserQuestion:

header: "Restart Scope"
question: "Phase issues detected. Which issues should be included in the restart?"
options:
  - label: "All issues"
    description: "Reset both general (G-) and phase (P1-, P2-, etc.) issues"
  - label: "General issues only"
    description: "Reset only general (G-) issues, leave phase issues unchanged"
  - label: "Cancel"
    description: "Abort the restart"

If "Cancel": Abort.

If "General issues only": Filter the plan to only include G- prefixed issues. Skip all P1-, P2-, etc. issues.

If "All issues": Continue with the full plan.

If no phase issues exist: Skip this question and proceed directly to confirmation.

3.2 Present the Plan

Present the plan to the user (filtered by scope if applicable):

Issues Restart Plan

DONE issues to delete (X):
- G-002: {title}
- P1-003: {title}  # Only shown if "All issues" selected
...

Active issues to renumber (by prefix group):

General (G-):
- G-001 -> G-001 (no change)
- G-003 -> G-002

# Phase sections only shown if "All issues" selected:
Phase 1 (P1-):
- P1-001 -> P1-001 (no change)
- P1-002 -> P1-002 (no change)
- P1-004 -> P1-003

Phase 2 (P2-):
- P2-001 -> P2-001 (no change)

Proceed with restart?

3.3 Confirm

Use AskUserQuestion:

header: "Confirm Issues Restart"
question: "This will delete DONE issues and renumber remaining issues. Proceed?"
options:
  - label: "Yes, restart issues"
    description: "Delete DONE issues and renumber remaining from 001"
  - label: "No, cancel"
    description: "Keep current state"

---

Step 4: Verify Spec Capture of DONE Issues

Before deleting DONE issues, check whether their decisions, outcomes, and related LOG.md entries are captured in the permanent specification files.

4.0 Preconditions

This step only runs if:

• There are DONE issues to delete (from Step 2)
• At least one spec file exists

If no spec file exists:

Note: No specification file found — skipping spec capture check.

Skip to Step 5.

4.1 Locate Spec Files

Find spec files using the same detection as other SIW skills:

1. Find .md files directly under siw/ (non-recursive), excluding: LOG.md, OPEN_ISSUES_OVERVIEW.md, SPEC_STRENGTHENING_PLAN.md, DISCOVERY_BRIEF.md, AUDIT_.*\.md
2. Never include files under siw/issues/ in spec detection
3. Find .md files under siw/supporting-specs/ if the directory exists
4. Store as spec_files (main) and supporting_spec_files

4.2 Read DONE Issue Files

For each DONE issue (filtered by scope from Step 3.1), read the issue file and extract capturable content:

| Content Category | Where to Find | What Qualifies | |---|---|---| | Decision | ## Decision section | Any non-placeholder content (not _To be filled_) | | Selected Option | ## Options with a chosen option, or ## Decision referencing an option | The chosen approach and rationale | | Implementation Notes | ## Technical Notes section | Concrete architectural or pattern choices | | Key Outcomes | ## Acceptance Criteria with checked items | Criteria that reveal design decisions (not just "tests pass") |

Skip issues whose files are missing or contain only placeholder content.

4.3 Read LOG.md for Related Entries

If siw/LOG.md exists, scan for entries referencing DONE issue IDs (in any format: G-002, ISSUE-G-002, etc.):

4.3.1 Decision Log entries — Scan ## Decision Log for decisions referencing DONE issues. Extract: decision number, title, problem, decision, rationale.

4.3.2 Current Progress entries — Scan ## Current Progress > ### Last Completed for references to DONE issues with implementation details.

4.3.3 Rejected Alternatives — Scan ## Rejected Alternatives Summary for rows linked to decisions that reference DONE issues.

4.3.4 Guiding Principles — If ## Guiding Principles has non-placeholder content and the spec has no matching Guiding Principles section, include as a capture candidate.

4.4 Compare Against Spec

For each capture candidate, check whether it already exists in the spec files using lightweight text search:

1. Decision heading match: Search spec files for explicit decision headings like ### Decision #N: (or #### Decision #N:). If found → Captured.
   • Do not treat a bare #N match as captured.
2. Keyword co-occurrence: Extract 2-3 distinctive terms from the candidate summary. If multiple terms co-occur within the same section of a spec file → Possibly captured.
3. Section existence check: For Guiding Principles, check if the spec has a non-empty ## Guiding Principles section → Captured if present.

Classify each candidate as: Captured / Possibly captured / Uncaptured.

4.5 Present to User

If all candidates are Captured:

Spec Capture Check: All decisions and outcomes from DONE issues are already reflected in the specification.

Proceed to Step 5.

If uncaptured or possibly-captured items exist, present grouped by source:

Spec Capture Check
==================

{N} items from DONE issues may not be captured in the specification:

From G-002 (API Design Pattern):
  1. [Decision] Chose explicit properties over IAuditable
     Source: siw/issues/ISSUE-G-002-api-design.md > Decision section
     Status: UNCAPTURED

  2. [LOG Decision #5] Make ActionByUserId Nullable
     Source: siw/LOG.md > Decision Log > Decision #5
     Status: UNCAPTURED

From P1-003 (Bug Fix):
  3. [Implementation Notes] Used retry pattern with exponential backoff
     Source: siw/issues/ISSUE-P1-003-retry-logic.md > Technical Notes
     Status: POSSIBLY CAPTURED - "retry" mentioned in spec but details differ

Cross-cutting:
  4. [Guiding Principles] 4 principles in LOG.md
     Source: siw/LOG.md > Guiding Principles
     Status: UNCAPTURED

Use AskUserQuestion:

header: "Spec Capture Check"
question: "Found uncaptured content from DONE issues. How should I proceed?"
options:
  - label: "Migrate all to spec"
    description: "Add all uncaptured items to the specification before deleting issues"
  - label: "Review each item"
    description: "Let me choose which items to migrate"
  - label: "Skip — proceed with deletion"
    description: "Delete DONE issues without migrating (content may be lost)"

If "Review each item": For each uncaptured item, use AskUserQuestion:

header: "Migrate to Spec?"
question: "Item {N}: [{category}] {summary}\n\nFrom {issue_id}: {issue_title}\nSource: {source}"
options:
  - label: "Migrate to spec"
    description: "Add this to the specification"
  - label: "Skip"
    description: "Not worth preserving"

If >10 uncaptured items, ask once for high-level handling first:

header: "Spec Capture Check"
question: "Found {N} uncaptured items from DONE issues. How should I proceed?"
options:
  - label: "Migrate all to spec"
    description: "Add all uncaptured items before deleting DONE issues"
  - label: "Review by category"
    description: "Choose categories to migrate in one step"
  - label: "Skip — proceed with deletion"
    description: "Delete DONE issues without migration (content may be lost)"

If "Review by category": use category-level multiSelect:

header: "Select Categories"
question: "Choose categories to migrate to the specification."
multiSelect: true
options:
  - label: "Decisions ({n})"
    description: "Migrate decision entries"
  - label: "Implementation notes ({n})"
    description: "Migrate architectural/pattern notes"
  - label: "Key outcomes ({n})"
    description: "Migrate decision-relevant acceptance outcomes"
  - label: "Guiding principles ({n})"
    description: "Migrate principles from LOG.md"

If no categories are selected, treat it as:

Spec Capture: Skipped (user chose to proceed without migration)

4.6 Migrate Selected Items to Spec

Route items to the appropriate spec file using the same patterns as issue-implement Step 10.4:

Routing rules for supporting specs:

• Data model decisions → *-data-model*.md
• API decisions → *-api*.md
• UI/frontend decisions → *-ui*.md or *-frontend*.md
• Default → main spec

For supporting specs: Update actual spec content (not just append to Design Decisions). If a decision changes an API endpoint, update the endpoint definition.

For main spec — Decisions:

Add to ## Design Decisions section (create if missing):

### Decision #{n}: {Title}
**Date:** {date from LOG.md or current date} | **Source:** {issue_id}

**Context:** {problem statement}
**Decision:** {chosen approach}
**Rationale:** {why}

For main spec — Guiding Principles:

Add to or create ## Guiding Principles section.

For main spec — Rejected Alternatives:

Add to ## Rejected Approaches or ## Design Decisions section:

### Rejected: {alternative name}
**For:** {purpose} | **Decision:** #{n}
**Why Rejected:** {reason}

4.7 Report Migration Results

Spec Capture: {N} items migrated
- {spec_file_1}: {n1} item(s)
- {spec_file_2}: {n2} item(s)

or

Spec Capture: Skipped (user chose to proceed without migration)

or

Spec Capture: All items already captured in spec

Proceed to Step 5.

---

Step 5: Delete DONE Issue Files

For each DONE issue:

# Delete using trash if available
if command -v trash &> /dev/null; then
    trash siw/issues/ISSUE-{prefix}-{number}-*.md
else
    rm -f siw/issues/ISSUE-{prefix}-{number}-*.md
fi

---

Step 6: Rename Remaining Issue Files

For each active issue that needs renumbering within its prefix group:

1. Read the issue file content
2. Update the issue number in the file header (e.g., # ISSUE-G-003: -> # ISSUE-G-002:)
3. Rewrite any short/full issue-id references inside the file body using the same renumberById / deletedById maps and collision-safe matching rules described in Step 8
   • This includes **Related:**, dependency lists such as Blocked by / Blocks, Parallelization Guidance, and any other prose references to issue ids
   • If a referenced issue was deleted, keep the original id and annotate it with (deleted: "{title}") instead of silently pointing it at a different renumbered issue
4. Update the **Status:** line if it references the issue number
5. Preserve any existing **Size:** / **Parallelization:** / **Mode:** metadata while updating ids
6. Write to new filename
7. Delete old file

Example:

# ISSUE-G-003-api-design.md -> ISSUE-G-002-api-design.md
# Update content: "# ISSUE-G-003:" -> "# ISSUE-G-002:"
mv siw/issues/ISSUE-G-003-api-design.md siw/issues/ISSUE-G-002-api-design.md

Important:

• Process each prefix group separately
• Process in reverse order within each group (highest number first) to avoid conflicts when renaming
• Classify matches against the original issue-file content first; do not chain replacements
• Do NOT merge issues between prefix groups

---

Step 7: Update siw/OPEN_ISSUES_OVERVIEW.md

Rebuild the issues table maintaining section groupings:

1. Remove all DONE rows from each section
2. Update issue numbers for remaining rows within each prefix group
3. Preserve the existing table schema for each section:
   • If the section uses | # | Title | Status | Size | Priority | Mode | Related |, keep Size and Mode
   • If the section uses | # | Title | Status | Size | Priority | Related |, keep Size
   • If the section uses the legacy | # | Title | Status | Priority | Related |, keep the legacy layout
4. Handle section-level metadata lines carefully:
   • Preserve non-**Parallelization:** metadata exactly as written.
   • For ## General, only recompute the **Parallelization:** summary if that line already exists:
     • If every real General issue shares the same section-level category/gating note, use that shared summary.
     • If real General issues disagree, set the summary to Mixed — see issue files for exact guidance.
     • If no real General issues remain, keep or restore the default summary from siw:init.
   • If an existing legacy General section has no **Parallelization:** line, keep it absent; do not add or restore one during reindex.
   • For phase sections, preserve the approved summary wording, but if the **Parallelization:** line names concrete issue ids (P1-003, ISSUE-P1-003, etc.), rewrite those ids with the same collision-safe renumberById / deletedById rules used for issue bodies and LOG.md so the gating note stays accurate after renumbering. If a legacy phase section has no **Parallelization:** line, keep it absent.
5. Preserve section headers (General, Phase 1, Phase 2, etc.) exactly as written (including any (DONE) marker on phase headers)

Before:

## General

**Parallelization:** Safe to parallelize

| # | Title | Status | Size | Priority | Mode | Related |
|---|-------|--------|------|----------|------|---------|
| G-001 | Setup | DONE | S | High | AUTO | |
| G-002 | Docs | READY | XS | Low | AUTO | |
| G-003 | Config | READY | S | Medium | HITL | |

## Phase 1: Foundation

**Parallelization:** Needs coordination

| # | Title | Status | Size | Priority | Mode | Related |
|---|-------|--------|------|----------|------|---------|
| P1-001 | Feature A | IN PROGRESS | M | High | AUTO | Task 1.0 |
| P1-002 | Feature B | DONE | S | High | AUTO | Task 2.0 |
| P1-003 | Bug Fix | READY | S | Medium | HITL | Task 3.0 |

After:

## General

**Parallelization:** Safe to parallelize

| # | Title | Status | Size | Priority | Mode | Related |
|---|-------|--------|------|----------|------|---------|
| G-001 | Docs | READY | XS | Low | AUTO | |
| G-002 | Config | READY | S | Medium | HITL | |

## Phase 1: Foundation

**Parallelization:** Needs coordination

| # | Title | Status | Size | Priority | Mode | Related |
|---|-------|--------|------|----------|------|---------|
| P1-001 | Feature A | IN PROGRESS | M | High | AUTO | Task 1.0 |
| P1-002 | Bug Fix | READY | S | Medium | HITL | Task 3.0 |

---

Step 8: Update siw/LOG.md

If siw/LOG.md exists, update issue number references to match the new numbering.

Process:

1. Read siw/LOG.md content - Skip this step if file doesn't exist

2. Build lookup maps from Steps 2 and 6:

   • renumberById: Map old numbers to new numbers within each prefix group (e.g., G-003 → G-002, P1-004 → P1-002)
   • deletedById: Map deleted DONE issue numbers to titles (e.g., G-001 → Setup)

3. Update issue references (collision-safe):

   • Patterns to match (both forms):
     • Short form: {prefix}-(\d{3}) (e.g., G-002, P1-003)
     • Full form: ISSUE-{prefix}-(\d{3}) (e.g., ISSUE-G-002, ISSUE-P1-003)
   • Where prefix is G, P1, P2, etc.
   • Match references against the original LOG.md content (do not chain incremental replacements)
   • For each original match, apply in this priority order:
     1. If the ID is in deletedById: Keep the original ID and append (deleted: "{escapedTitle}")
     2. Else if the ID is in renumberById: Replace with the new ID, preserving short/full form
   • Escape deleted titles before writing "{escapedTitle}":
     • Replace \ with \\
     • Replace " with \"
     • Replace newlines with spaces
   • Apply edits right-to-left (or with temporary placeholders) so a rewrite never changes how later matches are classified
   • Examples: G-001 → G-001 (deleted: "Setup"), ISSUE-G-001 → ISSUE-G-001 (deleted: "Setup")

4. Write updated LOG.md

Example mapping:

Renumber mapping:
- G-002 -> G-001
- G-003 -> G-002
- P1-003 -> P1-002

Deleted (annotated):
- G-001 ("Setup") -> G-001 (deleted: "Setup")
- P1-002 ("Feature B") -> P1-002 (deleted: "Feature B")

Example LOG.md updates:

# Before:
- **Task:** G-001 - Setup environment
- **Task:** G-002 - Feature B
- **Task:** P1-003 - Bug Fix
- **Impact:** Updated ISSUE-G-003 validation

# After:
- **Task:** G-001 (deleted: "Setup") - Setup environment
- **Task:** G-001 - Feature B
- **Task:** P1-002 - Bug Fix
- **Impact:** Updated ISSUE-G-002 validation

Important:

• Do NOT change Decision numbers (#1, #2, etc.) - these are permanent
• Annotate references to deleted (DONE) issues with (deleted: "{title}") to prevent collision with renumbered issues that now reuse the same number
• Use escaped titles in annotations (\ → \\, " → \") to keep LOG.md syntax unambiguous

---

Step 9: Report Results

Issues Restart Complete

Spec Capture:
- {N} items migrated
- {spec_file_1}: {n1} item(s)
- {spec_file_2}: {n2} item(s)
{Or: "All items already captured" / "Skipped by user" / "No spec file found"}

Deleted (X DONE issues):
- G-001: {title}
- P1-002: {title}

Renumbered (Y active issues):

General:
- G-002 -> G-001: {title}
- G-003 -> G-002: {title}

Phase 1:
- P1-003 -> P1-002: {title}

Updated files:
- siw/OPEN_ISSUES_OVERVIEW.md
- siw/LOG.md (N issue references updated)

Next Steps:
- Continue working on active issues
- Use /kramme:siw:issue-define to add new general issues (will start at G-00{next})
- Phase issues maintain their numbering within their group

LOG.md reporting variations:

• If LOG.md was updated: siw/LOG.md (N issue references updated)
• If LOG.md exists but no references found: siw/LOG.md (no issue references)
• If LOG.md doesn't exist: Omit from the list

---

Edge Cases

No DONE issues

No DONE issues found. Nothing to delete.

Active issues:
- G-001: {title}
- G-002: {title}
- P1-001: {title}

No renumbering needed since there are no gaps in any group.

Action: Report and exit (no changes needed).

All issues are DONE

All issues are DONE. This will clear all issues.

After restart, use /kramme:siw:issue-define to create new issues starting from G-001.

Use AskUserQuestion to confirm clearing all issues.

No gaps in numbering

If DONE issues are at the end of each sequence, only deletion is needed (no renumbering):

DONE issues to delete:
- G-003: {title}
- P1-004: {title}

Active issues (no renumbering needed):
- G-001: {title}
- G-002: {title}
- P1-001: {title}
- P1-002: {title}
- P1-003: {title}

Issue file missing

If an issue is in the overview but the file doesn't exist:

Warning: G-002 listed in overview but file not found.
Will remove from overview table.

LOG.md not found

If siw/LOG.md doesn't exist, skip the LOG.md update step (Step 8) silently. For the spec capture check (Step 4), only check DONE issue files directly — skip LOG.md analysis.

No issue references in LOG.md

If LOG.md exists but contains no issue reference patterns:

siw/LOG.md: No issue references found

Mixed prefix groups

Each prefix group is handled independently. Issues never move between groups:

G-001 (DONE), G-002 (READY), G-003 (READY)  →  G-001, G-002 (renumbered within G-)
P1-001 (READY), P1-002 (DONE), P1-003 (READY)  →  P1-001, P1-002 (renumbered within P1-)

References to deleted issues in LOG.md

Annotate references to deleted (DONE) issues with (deleted: "{title}") to disambiguate them from renumbered issues that now reuse the same number. Classify matches from original LOG.md text first (deleted mapping takes priority), then apply renumber replacements for non-deleted IDs. Escape title content before insertion (\ → \\, " → \", newlines → spaces).

No spec file exists

Skip Step 4 (Verify Spec Capture) entirely with a note:

Note: No specification file found — skipping spec capture check.

Proceed directly to deletion. This is valid when operating without a permanent spec.

DONE issue has only placeholder content

If a DONE issue file exists but contains only placeholder text (e.g., Decision section says _To be filled_, no Technical Notes), skip it silently during the spec capture check. Do not present empty items to the user.

General issues only (scope selection)

When user selects "General issues only":

• Only process G- prefixed issues
• Leave all P1-, P2-, etc. issues completely unchanged
• Spec capture check (Step 4) only examines G-prefixed DONE issues and G-prefixed LOG.md references
• LOG.md updates only apply to G- references
• Report shows only general issues in results

Issues Restart Complete (General Issues Only)

Deleted (X DONE general issues):
- G-001: {title}

Renumbered (Y active general issues):
- G-002 -> G-001: {title}
- G-003 -> G-002: {title}

Unchanged (phase issues not included):
- P1-001, P1-002, P1-003
- P2-001, P2-002

Updated files:
- siw/OPEN_ISSUES_OVERVIEW.md (general section only)
- siw/LOG.md (N general issue references updated)