Decision records¶
This page summarizes the decisions behind the audit method, design work, and evidence. It keeps the reasoning reviewable without turning the progress site into private working notes.
Decision summaries¶
DR-001: structured documentation¶
Category: Process
Use lightweight decision records and weekly journals. This keeps audit rationale, review feedback, and case-study source material organized while the work continues.
DR-002: finding-first contribution selection¶
Category: Pivot
Choose contributions from hardened findings, not from the easiest open issue. This moved the first audit-linked contribution from #790 to the measured contrast cluster that became PR #879.
DR-003: quality-first review strategy¶
Category: Process
Optimize for evidence quality and merge probability over PR count. This kept the project focused on finishing PR #879 cleanly before opening weaker work.
DR-004: device evidence before visual claims¶
Category: Technical
Use simulator screenshots and computed checks for general visual claims. If a claim depends on a specific device, get hardware confirmation or state that it still needs one.
DR-005: check touch targets before opening a navigation PR¶
Category: UX rationale
Measure touch-target sizes before treating them as a current failure. The checked targets cleared the 24 px minimum, so the result became a guardrail question rather than an automatic PR.
DR-006: Home Settings shortcut follow-up¶
Category: Design, superseded
Treat #790 as a possible Home Settings shortcut after the touch-target check. This decision was superseded when review questioned whether rare settings should take permanent Home-screen attention.
DR-007: park the Home Settings shortcut after review¶
Category: Pivot
PR #894 showed that Printer and Encryption were already available before wallet loading. The extra Home row helped a narrower post-wallet case while adding attention cost to every Home visit. The PR was closed and the lesson was recorded as navigation finding N2.
DR-008: put QR scanning inside text keypads¶
Category: UX rationale
Replace the separate Type/Scan choice with an optional QR action inside the existing keypad. A successful scan returns to the editable buffer, while cancellation or failure preserves the previous text. The initial 5x7 layout recommendation was later replaced by DR-010.
DR-009: expand navigation around choice burden and semantic clarity¶
Category: Audit-method correction
Replace the old depth and item-count pass rule with checks for label meaning, prominence, context before commit, recovery, and input effort. Correct N3 with current source and tests, then publish all six findings with their evidence boundaries. The audit records current behaviour without choosing or presenting an untested interface.
DR-010: preserve the 5x6 keypad¶
Category: Pivot
Place the uncommon scan action in an unused cell on the final special-character page. This keeps the existing key size on 2-inch devices and leaves the common typing path unchanged. Touch users can reach it with a right swipe, while button-only devices retain their existing focus controls.
DR-011: use progressive disclosure after mnemonic generation¶
Category: Design
Keep the wallet summary because policy, derivation, and passphrase choices
still need confirmation. Make Continue the common action and group
Passphrase and Customize under Wallet Options. This keeps the review
screen and specialist actions while reducing their prominence.
Decision trail¶
Start with a record system¶
The first process decision was to keep a numbered decision trail and weekly updates. The audit has several audiences: maintainers need precise findings and the final case study needs a clear account of what changed and why. Plain Markdown records were enough without adding more process overhead.
Move from target-first to finding-first¶
The early instinct was to pick a small issue and build around it. That produced a weak fit for #790 because the accessibility link was mostly retrofitted. The pivot was to harden a finding first, check whether the area was unclaimed, then choose any contribution. That made the contrast cluster the strongest first case and led to PR #879.
Separate simulator evidence from hardware claims¶
PR #879 showed why evidence type matters. Computed contrast ratios and simulator screenshots can support many theme-level claims, but they cannot prove every device-specific display behaviour. The Amigo info-panel case is a hardware-gated finding, not something the merged contrast PR claims to fix.
Treat screen fit as one piece of evidence¶
PR #894 showed that a technically small patch can still have a product cost. The row fit, but the main pre-login need was already covered by Settings. The audit now records attention cost, existing access, and task context alongside screen depth and item count.
Correct findings against current behaviour¶
The original N3 description did not match current Krux. Source and focused tests showed that mnemonic creation proceeds directly to the wallet summary. The audit was corrected instead of preserving a stronger but inaccurate claim.
Let review change the keypad layout¶
The first inline-scan layouts added a row or rearranged the fixed keys. Maintainer feedback pointed out the cost on 2-inch screens, so the next test used an empty cell on the last special-character page. That option kept the 5x6 grid, worked with touch and button navigation, and became the implemented Draft PR direction.
Keep the summary and change the hierarchy¶
The post-mnemonic work did not remove the wallet summary. It changed which action receives the most attention. The resulting Draft PR keeps the review context, makes the normal continuation clear, and moves less common choices into a nested menu.
Remaining evidence limits¶
- The Amigo info-panel contrast concern needs device-specific visual testing.
- The navigation audit does not include user testing of alternative menu categories or labels.
- Touch-target measurements identify a guardrail gap but do not prove a current task failure.
- Screenshots show current Krux behaviour only.