From ef6a38987579563ddc968ccbdb918c2cc8512e63 Mon Sep 17 00:00:00 2001 From: Jordan Ramos Date: Mon, 10 Aug 2026 10:53:49 -0600 Subject: [PATCH] Document driftChecker string-matching bug in steering notes Adds a Known Bugs & Lessons Learned section to the workflow steering file documenting the reconcileConfig message-matching failure pattern and the lesson: use type fields, not message substring matching, for programmatic finding identification. --- .kiro/steering/workflow.md | 39 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 .kiro/steering/workflow.md diff --git a/.kiro/steering/workflow.md b/.kiro/steering/workflow.md new file mode 100644 index 0000000..d9ceeee --- /dev/null +++ b/.kiro/steering/workflow.md @@ -0,0 +1,39 @@ +# Workflow & Context Gathering + +## Known Bugs & Lessons Learned + +Document bugs encountered during development that reveal systemic patterns worth remembering. + +### String-matching in reconcileConfig (driftChecker.js) — fixed 2026-08-10 + +`reconcileConfig()` identifies drift findings by matching substrings in `finding.message`. When `compareSchemaToDrift()` was written, it produced messages like `"Core column \"X\" is missing from all N detail sheet(s)"`, but reconcileConfig checked for `"is missing core column"` — a string that never appeared. The mismatch meant core column reconciliation silently did nothing, blocking compliance uploads when the report format changed. + +**Lesson:** Never match on message strings across function boundaries without a shared constant or a `type` field. If a finding type needs to be identified programmatically, add a machine-readable `type` property (e.g., `type: 'missing_core_col'`) rather than relying on human-readable messages that drift independently. + +**Compounding issue:** The reconcile logic also counted aggregated findings (always 1 per column) and compared against `detailSheetCount` (e.g., 18). This double-check was logically redundant — the detection already confirmed "missing from all" before emitting the finding — and always failed because 1 < 18. + +## Specs First + +Before making changes to any feature area, **always check `.kiro/specs/` for related spec folders first**. Specs contain the original requirements, design decisions, architecture diagrams, data models, and task breakdowns that informed the implementation. They provide critical context about: + +- Why a feature was built a certain way +- What data models and API contracts were agreed upon +- What correctness properties must hold +- What edge cases were considered + +Even if the code has evolved since the spec was written, the spec is the starting point for understanding intent. + +## Spec Folder Structure + +Each spec folder typically contains: + +- `requirements.md` — user stories and acceptance criteria +- `design.md` — architecture, data models, API contracts, error handling +- `tasks.md` — implementation task breakdown with completion status + +## When to Check Specs + +- Fixing bugs in a feature area — check the spec to understand intended behavior +- Adding to an existing feature — check the spec to understand design constraints +- Investigating unexpected behavior — the spec documents what "correct" looks like +- Refactoring — the spec documents which properties must be preserved