Browse Source
- Create software_development.mdc with evidence-first development principles - Add code path tracing requirements to research_diagnostic.mdc - Update base_context.mdc to reference new specialized rulesets - Create ADR and investigation report templates - Improve markdown formatting across all ruleset files Enhances development workflow with specialized guidance for: - Code review standards and evidence validation - Problem-solution validation and complexity assessment - Integration between generic and technical rulesetspull/165/head^2
Matthew Raymer
13 hours ago
5 changed files with 371 additions and 15 deletions
@ -0,0 +1,63 @@ |
|||||
|
# ADR Template |
||||
|
|
||||
|
## ADR-XXXX-YY-ZZ: [Short Title] |
||||
|
|
||||
|
**Date:** YYYY-MM-DD |
||||
|
**Status:** [PROPOSED | ACCEPTED | REJECTED | DEPRECATED | SUPERSEDED] |
||||
|
**Deciders:** [List of decision makers] |
||||
|
**Technical Story:** [Link to issue/PR if applicable] |
||||
|
|
||||
|
## Context |
||||
|
|
||||
|
[Describe the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts.] |
||||
|
|
||||
|
## Decision |
||||
|
|
||||
|
[Describe our response to these forces. We will use the past tense ("We will...").] |
||||
|
|
||||
|
## Consequences |
||||
|
|
||||
|
### Positive |
||||
|
- [List positive consequences] |
||||
|
|
||||
|
### Negative |
||||
|
- [List negative consequences or trade-offs] |
||||
|
|
||||
|
### Neutral |
||||
|
- [List neutral consequences or notes] |
||||
|
|
||||
|
## Alternatives Considered |
||||
|
|
||||
|
- **Alternative 1:** [Description] - [Why rejected] |
||||
|
- **Alternative 2:** [Description] - [Why rejected] |
||||
|
- **Alternative 3:** [Description] - [Why rejected] |
||||
|
|
||||
|
## Implementation Notes |
||||
|
|
||||
|
[Any specific implementation details, migration steps, or technical considerations] |
||||
|
|
||||
|
## References |
||||
|
|
||||
|
- [Link to relevant documentation] |
||||
|
- [Link to related ADRs] |
||||
|
- [Link to external resources] |
||||
|
|
||||
|
## Related Decisions |
||||
|
|
||||
|
- [List related ADRs or decisions] |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Usage Guidelines |
||||
|
|
||||
|
1. **Copy this template** for new ADRs |
||||
|
2. **Number sequentially** (ADR-001, ADR-002, etc.) |
||||
|
3. **Use descriptive titles** that clearly indicate the decision |
||||
|
4. **Include all stakeholders** in the deciders list |
||||
|
5. **Link to related issues** and documentation |
||||
|
6. **Update status** as decisions evolve |
||||
|
7. **Store in** `doc/architecture-decisions/` directory |
||||
|
description: |
||||
|
globs: |
||||
|
alwaysApply: false |
||||
|
--- |
||||
@ -0,0 +1,76 @@ |
|||||
|
# Investigation Report 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 |
||||
|
description: |
||||
|
globs: |
||||
|
alwaysApply: false |
||||
|
--- |
||||
@ -0,0 +1,178 @@ |
|||||
|
--- |
||||
|
alwaysApply: true |
||||
|
--- |
||||
|
|
||||
|
# Software Development Ruleset |
||||
|
|
||||
|
## Purpose |
||||
|
Specialized guidelines for software development tasks including code review, debugging, architecture decisions, and testing. |
||||
|
|
||||
|
## Core Principles |
||||
|
|
||||
|
### 1. Evidence-First Development |
||||
|
- **Code Citations Required**: Always cite specific file:line references when making claims |
||||
|
- **Execution Path Tracing**: Trace actual code execution before proposing architectural changes |
||||
|
- **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based" |
||||
|
|
||||
|
### 2. Code Review Standards |
||||
|
- **Trace Before Proposing**: Always trace execution paths before suggesting changes |
||||
|
- **Evidence Over Inference**: Prefer code citations over logical deductions |
||||
|
- **Scope Validation**: Confirm the actual scope of problems before proposing solutions |
||||
|
|
||||
|
### 3. Problem-Solution Validation |
||||
|
- **Problem Scope**: Does the solution address the actual problem? |
||||
|
- **Evidence Alignment**: Does the solution match the evidence? |
||||
|
- **Complexity Justification**: Is added complexity justified by real needs? |
||||
|
- **Alternative Analysis**: What simpler solutions were considered? |
||||
|
|
||||
|
## Required Workflows |
||||
|
|
||||
|
### Before Proposing Changes |
||||
|
- [ ] **Code Path Tracing**: Map execution flow from entry to exit |
||||
|
- [ ] **Evidence Collection**: Gather specific code citations and logs |
||||
|
- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred |
||||
|
- [ ] **Scope Validation**: Confirm the actual extent of the problem |
||||
|
|
||||
|
### During Solution Design |
||||
|
- [ ] **Evidence Alignment**: Ensure solution addresses proven problems |
||||
|
- [ ] **Complexity Assessment**: Justify any added complexity |
||||
|
- [ ] **Alternative Evaluation**: Consider simpler approaches first |
||||
|
- [ ] **Impact Analysis**: Assess effects on existing systems |
||||
|
|
||||
|
## Software-Specific Competence Hooks |
||||
|
|
||||
|
### Evidence Validation |
||||
|
- **"What code path proves this claim?"** |
||||
|
- **"How does data actually flow through the system?"** |
||||
|
- **"What am I assuming vs. what can I prove?"** |
||||
|
|
||||
|
### Code Tracing |
||||
|
- **"What's the execution path from user action to system response?"** |
||||
|
- **"Which components actually interact in this scenario?"** |
||||
|
- **"Where does the data originate and where does it end up?"** |
||||
|
|
||||
|
### Architecture Decisions |
||||
|
- **"What evidence shows this change is necessary?"** |
||||
|
- **"What simpler solution could achieve the same goal?"** |
||||
|
- **"How does this change affect the existing system architecture?"** |
||||
|
|
||||
|
## Integration with Other Rulesets |
||||
|
|
||||
|
### With base_context.mdc |
||||
|
- Inherits generic competence principles |
||||
|
- Adds software-specific evidence requirements |
||||
|
- Maintains collaboration and learning focus |
||||
|
|
||||
|
### With research_diagnostic.mdc |
||||
|
- Enhances investigation with code path tracing |
||||
|
- Adds evidence validation to diagnostic workflow |
||||
|
- Strengthens problem identification accuracy |
||||
|
|
||||
|
## Usage Guidelines |
||||
|
|
||||
|
### When to Use This Ruleset |
||||
|
- Code reviews and architectural decisions |
||||
|
- Bug investigation and debugging |
||||
|
- Performance optimization |
||||
|
- Feature implementation planning |
||||
|
- Testing strategy development |
||||
|
|
||||
|
### When to Combine with Others |
||||
|
- **base_context + software_development**: General development tasks |
||||
|
- **research_diagnostic + software_development**: Technical investigations |
||||
|
- **All three**: Complex architectural decisions or major refactoring |
||||
|
|
||||
|
## Self-Check (model, before responding) |
||||
|
- [ ] Code path traced and documented |
||||
|
- [ ] Evidence cited with specific file:line references |
||||
|
- [ ] Assumptions clearly flagged as proven vs. inferred |
||||
|
- [ ] Solution complexity justified by evidence |
||||
|
- [ ] Simpler alternatives considered and documented |
||||
|
- [ ] Impact on existing systems assessed |
||||
|
# Software Development Ruleset |
||||
|
|
||||
|
## Purpose |
||||
|
Specialized guidelines for software development tasks including code review, debugging, architecture decisions, and testing. |
||||
|
|
||||
|
## Core Principles |
||||
|
|
||||
|
### 1. Evidence-First Development |
||||
|
- **Code Citations Required**: Always cite specific file:line references when making claims |
||||
|
- **Execution Path Tracing**: Trace actual code execution before proposing architectural changes |
||||
|
- **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based" |
||||
|
|
||||
|
### 2. Code Review Standards |
||||
|
- **Trace Before Proposing**: Always trace execution paths before suggesting changes |
||||
|
- **Evidence Over Inference**: Prefer code citations over logical deductions |
||||
|
- **Scope Validation**: Confirm the actual scope of problems before proposing solutions |
||||
|
|
||||
|
### 3. Problem-Solution Validation |
||||
|
- **Problem Scope**: Does the solution address the actual problem? |
||||
|
- **Evidence Alignment**: Does the solution match the evidence? |
||||
|
- **Complexity Justification**: Is added complexity justified by real needs? |
||||
|
- **Alternative Analysis**: What simpler solutions were considered? |
||||
|
|
||||
|
## Required Workflows |
||||
|
|
||||
|
### Before Proposing Changes |
||||
|
- [ ] **Code Path Tracing**: Map execution flow from entry to exit |
||||
|
- [ ] **Evidence Collection**: Gather specific code citations and logs |
||||
|
- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred |
||||
|
- [ ] **Scope Validation**: Confirm the actual extent of the problem |
||||
|
|
||||
|
### During Solution Design |
||||
|
- [ ] **Evidence Alignment**: Ensure solution addresses proven problems |
||||
|
- [ ] **Complexity Assessment**: Justify any added complexity |
||||
|
- [ ] **Alternative Evaluation**: Consider simpler approaches first |
||||
|
- [ ] **Impact Analysis**: Assess effects on existing systems |
||||
|
|
||||
|
## Software-Specific Competence Hooks |
||||
|
|
||||
|
### Evidence Validation |
||||
|
- **"What code path proves this claim?"** |
||||
|
- **"How does data actually flow through the system?"** |
||||
|
- **"What am I assuming vs. what can I prove?"** |
||||
|
|
||||
|
### Code Tracing |
||||
|
- **"What's the execution path from user action to system response?"** |
||||
|
- **"Which components actually interact in this scenario?"** |
||||
|
- **"Where does the data originate and where does it end up?"** |
||||
|
|
||||
|
### Architecture Decisions |
||||
|
- **"What evidence shows this change is necessary?"** |
||||
|
- **"What simpler solution could achieve the same goal?"** |
||||
|
- **"How does this change affect the existing system architecture?"** |
||||
|
|
||||
|
## Integration with Other Rulesets |
||||
|
|
||||
|
### With base_context.mdc |
||||
|
- Inherits generic competence principles |
||||
|
- Adds software-specific evidence requirements |
||||
|
- Maintains collaboration and learning focus |
||||
|
|
||||
|
### With research_diagnostic.mdc |
||||
|
- Enhances investigation with code path tracing |
||||
|
- Adds evidence validation to diagnostic workflow |
||||
|
- Strengthens problem identification accuracy |
||||
|
|
||||
|
## Usage Guidelines |
||||
|
|
||||
|
### When to Use This Ruleset |
||||
|
- Code reviews and architectural decisions |
||||
|
- Bug investigation and debugging |
||||
|
- Performance optimization |
||||
|
- Feature implementation planning |
||||
|
- Testing strategy development |
||||
|
|
||||
|
### When to Combine with Others |
||||
|
- **base_context + software_development**: General development tasks |
||||
|
- **research_diagnostic + software_development**: Technical investigations |
||||
|
- **All three**: Complex architectural decisions or major refactoring |
||||
|
|
||||
|
## Self-Check (model, before responding) |
||||
|
- [ ] Code path traced and documented |
||||
|
- [ ] Evidence cited with specific file:line references |
||||
|
- [ ] Assumptions clearly flagged as proven vs. inferred |
||||
|
- [ ] Solution complexity justified by evidence |
||||
|
- [ ] Simpler alternatives considered and documented |
||||
|
- [ ] Impact on existing systems assessed |
||||
Loading…
Reference in new issue