# Sprint Change Proposal

**Date:** 2026-03-13  
**Feature:** XLSX Jurisdiction Import  
**Change Type:** Correct Course during implementation  
**Scope Classification:** Minor

## 1. Issue Summary

The XLSX jurisdiction import feature was implemented from the original quick spec, but the business rules changed during implementation review.

New required behavior:

- malformed `Jurisdiction` rows must show the full imported record, not just row number and reason
- unmatched `JCode` rows must now be inserted into `Jurisdiction` instead of being skipped
- `IMB_Digits` build failures must also show the full imported record

Context:

- the current quick spec explicitly says unmatched `JCode` rows should be skipped
- the current implementation summary/error reporting is too terse for operators to identify the bad row without manually reopening the workbook

Evidence:

- current spec says unmatched `JCode` rows are skipped
- current implementation logs row-level errors as short messages only
- stakeholder clarified the corrected behavior after implementation had already started

## 2. Impact Analysis

### Epic Impact

No epics or stories artifacts exist for this quick-flow change, so there is no epic backlog to rewrite.

### Story Impact

No formal story artifacts exist. The impact is limited to the current quick-spec-driven implementation.

### Artifact Conflicts

Affected artifacts:

- `/workspace/_bmad-output/implementation-artifacts/tech-spec-add-xlsx-jurisdiction-import.md`
- `/workspace/App/Controllers/Jurisdiction/JurisdictionController.asp`
- `/workspace/App/Views/Jurisdiction/import.asp`
- `/workspace/App/DomainModels/JurisdictionRepository.asp` if insert support needs refinement

Conflicts discovered:

- current spec says unmatched `JCode` rows should be skipped, but new requirement says they must be inserted
- current spec requires row number and failure reason, but new requirement also needs full row content displayed for specific failures

### Technical Impact

- controller logic must change from update-or-skip to update-or-insert
- import summary counters must distinguish `updated` and `inserted`
- row error formatting must include the full workbook row payload for:
  - malformed `Jurisdiction`
  - IMB digit build failure
- UI summary labels must align with the new counters
- acceptance criteria and task tracking in the quick spec must be corrected

## 3. Recommended Approach

### Chosen Path

**Direct Adjustment**

### Rationale

This is a bounded feature correction, not a broad replanning event. The existing implementation is already concentrated in one controller and one view, so the safest path is to update the quick spec and then amend the implementation directly.

### Effort / Risk

- **Effort:** Low to Medium
- **Risk:** Medium

Primary risk areas:

- insert path must not create malformed or partial `Jurisdiction` records
- operator-facing error rendering must remain readable when full row payloads are shown
- summary counters and wording must stay consistent with the new behavior

### Timeline Impact

Small extension to the current implementation pass. No broader program impact identified.

## 4. Detailed Change Proposals

### A. Quick Spec Updates

#### A1. Unmatched `JCode` behavior

**OLD**

- Rows with extracted `JCode` values not found in `Jurisdiction` should be skipped and counted in the final summary instead of inserted.
- Acceptance criteria describe unmatched rows as skipped with no insert.

**NEW**

- Rows with extracted `JCode` values not found in `Jurisdiction` should be inserted into `Jurisdiction`.
- Final summary should track inserted rows separately from updated rows.

**Rationale**

This aligns the artifact with the corrected business rule.

#### A2. Full-record row errors

**OLD**

- Final result exposes row number and failure reason.

**NEW**

- Final result exposes row number, failure reason, and the full imported record for failure cases where operator review is needed.

**Rationale**

Operators need enough detail to identify and repair bad workbook rows quickly.

#### A3. IMB digit failure reporting

**OLD**

- `IMB_Digits` failures are treated as row-level failures with summary text.

**NEW**

- `IMB_Digits` failures must include the full row content in the error output.

**Rationale**

The source data causing the failure must be visible without cross-referencing the spreadsheet manually.

### B. Implementation Updates

#### B1. Insert-on-missing `JCode`

**OLD**

- `FindByJCode` failure increments unmatched count and records an error.

**NEW**

- `FindByJCode` failure creates a new jurisdiction model and inserts it using the imported values.
- Import summary tracks `insertedCount`.

**Rationale**

This is the main behavioral correction.

#### B2. Full-row error formatting

**OLD**

- Example: `Row 14: Jurisdiction field is missing a code in parentheses.`

**NEW**

- Example: `Row 14: Jurisdiction field is missing a code in parentheses. Record: County=..., Jurisdiction=..., Mailing Address=..., City & Township=..., ZIP + 4=..., Mailer ID Option 1=...`

**Rationale**

This directly satisfies the new operational requirement.

#### B3. UI counter updates

**OLD**

- `updated`, `unmatched`, `invalid`, `failed`, `duplicates`

**NEW**

- `updated`, `inserted`, `invalid`, `failed`, `duplicates`

**Rationale**

The UI should reflect what the import actually does.

## 5. Implementation Handoff

### Scope

**Minor**

### Handoff Recipients

- Development implementation pass
- Optional technical writer/doc refresh after code is aligned

### Responsibilities

- Update quick spec to reflect corrected behavior
- Amend controller logic to insert on missing `JCode`
- Add full-record context to specified error cases
- Update import UI summary wording/counters
- Verify with manual IIS test using the sample workbook and crafted failure rows

### Success Criteria

- malformed `Jurisdiction` rows display full record details
- missing `JCode` rows insert new jurisdictions successfully
- IMB digit failures display full record details
- import summary distinguishes updated vs inserted
- quick spec reflects final corrected behavior and task state

