forked from jsnbuchanan/crowd-funder-for-time-pwa
refactor(cursor-rules): restructure rules architecture with meta-rule system
- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories
This commit is contained in:
178
.cursor/rules/development/investigation_report_example.mdc
Normal file
178
.cursor/rules/development/investigation_report_example.mdc
Normal file
@@ -0,0 +1,178 @@
|
||||
# Investigation Report Example
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-19
|
||||
**Status**: 🎯 **ACTIVE** - Investigation methodology example
|
||||
|
||||
## Investigation — Registration Dialog Test Flakiness
|
||||
|
||||
## Objective
|
||||
|
||||
Identify root cause of flaky tests related to registration dialogs in contact
|
||||
import scenarios.
|
||||
|
||||
## System Map
|
||||
|
||||
- User action → ContactInputForm → ContactsView.addContact() →
|
||||
|
||||
handleRegistrationPrompt()
|
||||
|
||||
- setTimeout(1000ms) → Modal dialog → User response → Registration API call
|
||||
|
||||
- Test execution → Wait for dialog → Assert dialog content → Click response
|
||||
|
||||
button
|
||||
|
||||
## Findings (Evidence)
|
||||
|
||||
- **1-second timeout causes flakiness** — evidence:
|
||||
|
||||
`src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in
|
||||
handleRegistrationPrompt()
|
||||
|
||||
- **Import flow bypasses dialogs** — evidence:
|
||||
|
||||
`src/views/ContactImportView.vue:500-520`; importContacts() calls
|
||||
$insertContact() directly, no handleRegistrationPrompt()
|
||||
|
||||
- **Dialog only appears in direct add flow** — evidence:
|
||||
|
||||
`src/views/ContactsView.vue:774-800`; addContact() calls
|
||||
handleRegistrationPrompt() after database insert
|
||||
|
||||
## Hypotheses & Failure Modes
|
||||
|
||||
- H1: 1-second timeout makes dialog appearance unpredictable; would fail when
|
||||
|
||||
tests run faster than 1000ms
|
||||
|
||||
- H2: Test environment timing differs from development; watch for CI vs local
|
||||
|
||||
test differences
|
||||
|
||||
## Corrections
|
||||
|
||||
- Updated: "Multiple dialogs interfere with imports" → "Import flow never
|
||||
|
||||
triggers dialogs - they only appear in direct contact addition"
|
||||
|
||||
- Updated: "Complex batch registration needed" → "Simple timeout removal and
|
||||
|
||||
test mode flag sufficient"
|
||||
|
||||
## Diagnostics (Next Checks)
|
||||
|
||||
- [ ] Repro on CI environment vs local
|
||||
|
||||
- [ ] Measure actual dialog appearance timing
|
||||
|
||||
- [ ] Test with setTimeout removed
|
||||
|
||||
- [ ] Verify import flow doesn't call handleRegistrationPrompt
|
||||
|
||||
## Risks & Scope
|
||||
|
||||
- Impacted: Contact addition tests, registration workflow tests; Data: None;
|
||||
|
||||
Users: Test suite reliability
|
||||
|
||||
## Decision / Next Steps
|
||||
|
||||
- Owner: Development Team; By: 2025-01-28
|
||||
|
||||
- Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests
|
||||
|
||||
pass consistently
|
||||
|
||||
## References
|
||||
|
||||
- `src/views/ContactsView.vue:971-1000`
|
||||
|
||||
- `src/views/ContactImportView.vue:500-520`
|
||||
|
||||
- `src/views/ContactsView.vue:774-800`
|
||||
|
||||
## Competence Hooks
|
||||
|
||||
- Why this works: Code path tracing revealed separate execution flows,
|
||||
|
||||
evidence disproved initial assumptions
|
||||
|
||||
- Common pitfalls: Assuming related functionality without tracing execution
|
||||
|
||||
paths, over-engineering solutions to imaginary problems
|
||||
|
||||
- Next skill: Learn to trace code execution before proposing architectural
|
||||
|
||||
changes
|
||||
|
||||
- Teach-back: "What evidence shows that contact imports bypass registration
|
||||
|
||||
dialogs?"
|
||||
|
||||
## Key Learning Points
|
||||
|
||||
### Evidence-First Approach
|
||||
|
||||
This investigation demonstrates the importance of:
|
||||
|
||||
1. **Tracing actual code execution** rather than making assumptions
|
||||
|
||||
2. **Citing specific evidence** with file:line references
|
||||
|
||||
3. **Validating problem scope** before proposing solutions
|
||||
|
||||
4. **Considering simpler alternatives** before complex architectural changes
|
||||
|
||||
### Code Path Tracing Value
|
||||
|
||||
By tracing the execution paths, we discovered:
|
||||
|
||||
- Import flow and direct add flow are completely separate
|
||||
|
||||
- The "multiple dialog interference" problem didn't exist
|
||||
|
||||
- A simple timeout removal would solve the actual issue
|
||||
|
||||
### Prevention of Over-Engineering
|
||||
|
||||
The investigation prevented:
|
||||
|
||||
- Unnecessary database schema changes
|
||||
|
||||
- Complex batch registration systems
|
||||
|
||||
- Migration scripts for non-existent problems
|
||||
|
||||
- Architectural changes based on assumptions
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active investigation methodology
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: software_development.mdc
|
||||
**Stakeholders**: Development team, QA team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Investigation
|
||||
|
||||
- [ ] **Problem Definition**: Clearly define the problem to investigate
|
||||
- [ ] **Scope Definition**: Determine investigation scope and boundaries
|
||||
- [ ] **Methodology Planning**: Plan investigation approach and methods
|
||||
- [ ] **Resource Assessment**: Identify required resources and tools
|
||||
|
||||
### During Investigation
|
||||
|
||||
- [ ] **Evidence Collection**: Gather relevant evidence and data systematically
|
||||
- [ ] **Code Path Tracing**: Map execution flow for software investigations
|
||||
- [ ] **Analysis**: Analyze evidence using appropriate methods
|
||||
- [ ] **Documentation**: Document investigation process and findings
|
||||
|
||||
### After Investigation
|
||||
|
||||
- [ ] **Synthesis**: Synthesize findings into actionable insights
|
||||
- [ ] **Report Creation**: Create comprehensive investigation report
|
||||
- [ ] **Recommendations**: Provide clear, actionable recommendations
|
||||
- [ ] **Team Communication**: Share findings and next steps with team
|
||||
Reference in New Issue
Block a user