Discrepancy to Increment Command

Convert one or more brownfield discrepancies into a new increment for systematic documentation improvement.

Usage

/sw:discrepancy-to-increment DISC-0001
/sw:discrepancy-to-increment DISC-0001 DISC-0002 DISC-0003
/sw:discrepancy-to-increment --module payment-service

Arguments

<discrepancy-ids>: One or more discrepancy IDs to convert (e.g., DISC-0001 DISC-0002)
--module <name>: Convert all pending discrepancies for a specific module
--type <type>: Convert all discrepancies of a specific type
--priority <level>: Convert all discrepancies at or above a priority level
--dry-run: Preview what would be created without making changes

Process

Read Discrepancy Details
- Load specified discrepancies from .specweave/discrepancies/
- Verify all discrepancies exist and are in pending status
Group by Module (if multiple)
- If discrepancies span multiple modules, ask if user wants:
  - Single increment covering all modules
  - Separate increments per module

Generate Increment ID with Validation (v1.0.102+)

Get next available increment number

Validate increment number using increment-validator:

import { validateIncrementNumber, logValidationResult } from './src/core/increment-validator.js';

// Get all existing increments
const existingIncrements = [
  ...fs.readdirSync('.specweave/increments/'),
  ...fs.readdirSync('.specweave/increments/_archive/').map(f => `_archive/${f}`),
].filter(f => /^\d{4}-/.test(f));

// Get next number
const nextNumber = getNextIncrementNumber();

// Validate (should always be sequential for discrepancy-to-increment)
const result = validateIncrementNumber(nextNumber, existingIncrements);
logValidationResult(result);

if (!result.isValid) {
  throw new Error('Cannot generate increment ID. See validation errors above.');
}

// Use validated number
const incrementId = `${nextNumber}-${moduleName}-docs-improvement`;

Include discrepancy context in spec.md
Generate user stories from discrepancies
Link code/doc locations

Update Discrepancy Status
- Change status from pending to in-progress
- Add incrementId reference
On Increment Completion
- When increment closes via /sw:done
- All linked discrepancies auto-marked resolved
- Archived to resolved/YYYY-MM/

Example Output

🔄 Converting discrepancies to increment...

Selected discrepancies:
  ├─ DISC-0001: missing-docs (payment-service)
  ├─ DISC-0002: missing-docs (payment-service)
  └─ DISC-0003: stale-docs (payment-service)

Module: payment-service
Total: 3 discrepancies

Generated increment: 0087-payment-docs-improvement

📝 spec.md created with:
  • 1 user story: Document payment-service module
  • 3 acceptance criteria (one per discrepancy)
  • Links to affected code locations

Updated discrepancy status:
  ├─ DISC-0001: pending → in-progress
  ├─ DISC-0002: pending → in-progress
  └─ DISC-0003: pending → in-progress

Next steps:
  1. Review: .specweave/increments/0087-payment-docs-improvement/spec.md
  2. Plan: /sw:plan 0087
  3. Execute: /sw:do 0087

Generated Spec Structure

---
increment: 0087-payment-docs-improvement
status: planning
type: documentation
---

# Documentation Improvement: payment-service

## Context

This increment addresses documentation gaps detected during brownfield analysis.

### Source Discrepancies

| ID | Type | Priority | Summary |
|----|------|----------|---------|
| DISC-0001 | missing-docs | high | 12 undocumented exports |
| DISC-0002 | missing-docs | medium | processPayment function lacks docs |
| DISC-0003 | stale-docs | high | Payment flow diagram outdated |

## User Story

### US-001: Document payment-service Module

**As a** new developer joining the team,
**I want** comprehensive documentation for the payment-service module,
**So that** I can understand and contribute to the payment flow.

#### Acceptance Criteria

- [ ] **AC-US1-01**: Document all 12 undocumented exports (DISC-0001)
- [ ] **AC-US1-02**: Add JSDoc to processPayment function (DISC-0002)
- [ ] **AC-US1-03**: Update payment flow diagram to match current implementation (DISC-0003)

## Technical Notes

### Affected Files

From DISC-0001:
- `src/payment/processor.ts`
- `src/payment/validator.ts`
- `src/payment/types.ts`

From DISC-0003:
- `docs/modules/payment.md` (diagram needs update)

Completion Hook

When the increment is closed with /sw:done:

// Automatically triggered by increment completion
async function onIncrementComplete(incrementId: string) {
  const manager = new BrownfieldDiscrepancyManager(projectPath);

  // Find all discrepancies linked to this increment
  const discrepancies = await manager.listDiscrepancies({
    incrementId,
    status: 'in-progress'
  });

  // Resolve each discrepancy
  for (const disc of discrepancies) {
    await manager.resolveDiscrepancy(disc.id, {
      type: 'doc-updated',
      resolvedAt: new Date().toISOString(),
      resolvedBy: 'increment-completion'
    });
  }

  console.log(`✅ Resolved ${discrepancies.length} discrepancies`);
}

/sw:discrepancies - View pending discrepancies
/sw:increment - Create new increment manually
/sw:done - Complete increment (triggers resolution)

/discrepancy-to-increment