tracking_kits/_bmad-output/planning-artifacts/sprint-change-proposal-2026-03-13.md

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