From fbf7b02e19fde2612ef4d464b489afbf3df45846 Mon Sep 17 00:00:00 2001 From: David Hu <159687+divad12@users.noreply.github.com> Date: Mon, 29 Jun 2026 20:09:39 -0300 Subject: [PATCH] task-observer: add docs/ai/product-shakedown.md and routing entry --- .claude/AGENTS.md | 1 + docs/ai/product-shakedown.md | 39 ++++++++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+) create mode 100644 docs/ai/product-shakedown.md diff --git a/.claude/AGENTS.md b/.claude/AGENTS.md index 6fb4ae6..4ed2472 100644 --- a/.claude/AGENTS.md +++ b/.claude/AGENTS.md @@ -125,6 +125,7 @@ Do not run full validation suites after every small edit by habit. Run the narro | Editing AGENTS.md, .agents/skills/, docs/ai/ | writing-docs.md | | Maintaining or troubleshooting ask-intern | ask-intern.md | | Operating or changing the learning system | learning-system.md | + | Running product shakedowns, bug bashes, shakedown triage | product-shakedown.md | - Re-read the hard rules before implementation. ## Session Tools diff --git a/docs/ai/product-shakedown.md b/docs/ai/product-shakedown.md new file mode 100644 index 0000000..35f55ba --- /dev/null +++ b/docs/ai/product-shakedown.md @@ -0,0 +1,39 @@ +> **IMPORTANT: Before reading, check if you already read this file earlier in this session. If yes, skip the read and announce "Context already loaded: product-shakedown.md (re-using from earlier)". If no, read it and announce "Context loaded: product-shakedown.md".** + +# Product Shakedown + +## Contract + +- After any browser flow that generates or persists data, run a targeted DB invariant check for the exact constraint that motivated the investigation. Browser test success does not prove generated-data quality. +- Treat optimistic update freshness, visible flicker, stale cache, and revert-then-correct behavior as **bugs**. These break trust in saved work and belong in bug bashing, not enhancement queues. +- Keep a scale-realism scenario backlog. Run at least one large-fixture shakedown (e.g. 60 groups, 500–1000 participants) per milestone, exercising every major surface — not only the main feature path on a small fixture. +- Bug class severity is determined by user-visible trust breakage, not engineering effort. + +## Severity Calibration + +Prioritize in this order during a bug bash: + +1. **Interaction timing regressions** — optimistic updates that flicker, revert, or double-update; stale data visible after a save; counts that disagree with underlying data. +2. **Persisted-data invariants** — generated data that violates uniqueness, coverage, or ordering constraints, only visible via DB state inspection. +3. **Surface gaps** — tabs, views, or API endpoints not exercised under realistic load. +4. **Orientation affordances** — legends, hover states, read-only markers. Valuable UX improvements, but route these to enhancements unless they block task completion or corrupt architect trust in the data. + +## Persisted-Data Verification Pattern + +For any bug discovered in generated or persisted state: + +1. Run the browser flow that exercises generation. +2. Run a targeted DB invariant check for the exact constraint (uniqueness across a partition, max per group, coverage across legs, etc.). +3. Record the invariant and the observed result in the scratch or triage doc. +4. Do not close the bug until the DB check passes. Browser suite green is not sufficient. + +## Scale Realism + +Single-group or small-fixture shakedowns overfit to the happy path. Bugs in tab navigation, group selectors, counts, and auto-generated content diversity often only appear under realistic event load. Add at least one large-fixture shakedown scenario per milestone. + +Track single-group assumptions as a first-class shakedown risk. A surface that works for one group may silently break for 60. + +## Notes + +- "No user-facing impact" is not a valid triage for optimistic flicker. Architects lose trust in saved state when the UI appears to revert. +- End-to-end flow success ≠ generated data quality. Pair browser flows with DB invariant checks for generated-data bugs.