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:
Matthew Raymer
262
.cursor/rules/development/research_diagnostic.mdc
Normal file
262
.cursor/rules/development/research_diagnostic.mdc
Normal file
@@ -0,0 +1,262 @@
|
||||
---
|
||||
description: Use this workflow when doing **pre-implementation research, defect
|
||||
investigations with uncertain repros, or clarifying system architecture and
|
||||
behaviors**.
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
```json
|
||||
|
||||
{
|
||||
"coaching_level": "light",
|
||||
"socratic_max_questions": 2,
|
||||
"verbosity": "concise",
|
||||
"timebox_minutes": null,
|
||||
"format_enforcement": "strict"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
# Research & Diagnostic Workflow (R&D)
|
||||
|
||||
## Purpose
|
||||
|
||||
Provide a **repeatable, evidence-first** workflow to investigate features and
|
||||
defects **before coding**. Outputs are concise reports, hypotheses, and next
|
||||
steps—**not** code changes.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Pre-implementation research for new features
|
||||
|
||||
- Defect investigations (repros uncertain, user-specific failures)
|
||||
|
||||
- Architecture/behavior clarifications (e.g., auth flows, merges, migrations)
|
||||
|
||||
---
|
||||
|
||||
## Enhanced with Software Development Ruleset
|
||||
|
||||
When investigating software issues, also apply:
|
||||
|
||||
- **Code Path Tracing**: Required for technical investigations
|
||||
|
||||
- **Evidence Validation**: Ensure claims are code-backed
|
||||
|
||||
- **Solution Complexity Assessment**: Justify architectural changes
|
||||
|
||||
---
|
||||
|
||||
## Output Contract (strict)
|
||||
|
||||
1) **Objective** — 1–2 lines
|
||||
2) **System Map (if helpful)** — short diagram or bullet flow (≤8 bullets)
|
||||
3) **Findings (Evidence-linked)** — bullets; each with file/function refs
|
||||
4) **Hypotheses & Failure Modes** — short list, each testable
|
||||
5) **Corrections** — explicit deltas from earlier assumptions (if any)
|
||||
6) **Diagnostics** — what to check next (logs, DB, env, repro steps)
|
||||
7) **Risks & Scope** — what could break; affected components
|
||||
8) **Decision/Next Steps** — what we'll do, who's involved, by when
|
||||
9) **References** — code paths, ADRs, docs
|
||||
10) **Competence & Collaboration Hooks** — brief, skimmable
|
||||
|
||||
> Keep total length lean. Prefer links and bullets over prose.
|
||||
|
||||
---
|
||||
|
||||
## Quickstart Template
|
||||
|
||||
Copy/paste and fill:
|
||||
|
||||
```md
|
||||
|
||||
# Investigation — <short title>
|
||||
|
||||
## Objective
|
||||
|
||||
<one or two lines>
|
||||
|
||||
## System Map
|
||||
|
||||
- <module> → <function> → <downstream>
|
||||
|
||||
- <data path> → <db table> → <api>
|
||||
|
||||
## Findings (Evidence)
|
||||
|
||||
- <claim> —
|
||||
|
||||
evidence: `src/path/file.ts:function` (lines X–Y); log snippet/trace id
|
||||
|
||||
- <claim> — evidence: `...`
|
||||
|
||||
## Hypotheses & Failure Modes
|
||||
|
||||
- H1: <hypothesis>; would fail when <condition>
|
||||
|
||||
- H2: <hypothesis>; watch for <signal>
|
||||
|
||||
## Corrections
|
||||
|
||||
- Updated: <old statement> → <new statement with evidence>
|
||||
|
||||
## Diagnostics (Next Checks)
|
||||
|
||||
- [ ] Repro on <platform/version>
|
||||
|
||||
- [ ] Inspect <table/store> for <record>
|
||||
|
||||
- [ ] Capture <log/trace>
|
||||
|
||||
## Risks & Scope
|
||||
|
||||
- Impacted: <areas/components>; Data: <tables/keys>; Users: <segments>
|
||||
|
||||
## Decision / Next Steps
|
||||
|
||||
- Owner: <name>; By: <date> (YYYY-MM-DD)
|
||||
|
||||
- Action: <spike/bugfix/ADR>; Exit criteria: <binary checks>
|
||||
|
||||
## References
|
||||
|
||||
- `src/...`
|
||||
|
||||
- ADR: `docs/adr/xxxx-yy-zz-something.md`
|
||||
|
||||
- Design: `docs/...`
|
||||
|
||||
## Competence Hooks
|
||||
|
||||
- Why this works: <≤3 bullets>
|
||||
|
||||
- Common pitfalls: <≤3 bullets>
|
||||
|
||||
- Next skill: <≤1 item>
|
||||
|
||||
- Teach-back: "<one question>"
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Evidence Quality Bar
|
||||
|
||||
- **Cite the source** (file:func, line range if possible).
|
||||
|
||||
- **Prefer primary evidence** (code, logs) over inference.
|
||||
|
||||
- **Disambiguate platform** (Web/Capacitor/Electron) and **state** (migration,
|
||||
|
||||
auth).
|
||||
|
||||
- **Note uncertainty** explicitly.
|
||||
|
||||
---
|
||||
|
||||
## Code Path Tracing (Required for Software Investigations)
|
||||
|
||||
Before proposing solutions, trace the actual execution path:
|
||||
|
||||
- [ ] **Entry Points**:
|
||||
|
||||
Identify where the flow begins (user action, API call, etc.)
|
||||
|
||||
- [ ] **Component Flow**: Map which components/methods are involved
|
||||
|
||||
- [ ] **Data Path**: Track how data moves through the system
|
||||
|
||||
- [ ] **Exit Points**: Confirm where the flow ends and what results
|
||||
|
||||
- [ ] **Evidence Collection**: Gather specific code citations for each step
|
||||
|
||||
---
|
||||
|
||||
## Collaboration Hooks
|
||||
|
||||
- **Syncs:** 10–15m with QA/Security/Platform owners for high-risk areas.
|
||||
|
||||
- **ADR:** Record major decisions; link here.
|
||||
|
||||
- **Review:** Share repro + diagnostics checklist in PR/issue.
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Rulesets
|
||||
|
||||
### With software_development.mdc
|
||||
|
||||
- **Enhanced Evidence Validation**:
|
||||
|
||||
Use code path tracing for technical investigations
|
||||
|
||||
- **Architecture Assessment**:
|
||||
|
||||
Apply complexity justification to proposed solutions
|
||||
|
||||
- **Impact Analysis**: Assess effects on existing systems before recommendations
|
||||
|
||||
### With base_context.mdc
|
||||
|
||||
- **Competence Building**: Focus on technical investigation skills
|
||||
|
||||
- **Collaboration**: Structure outputs for team review and discussion
|
||||
|
||||
---
|
||||
|
||||
## Self-Check (model, before responding)
|
||||
|
||||
- [ ] Output matches the **Output Contract** sections.
|
||||
|
||||
- [ ] Each claim has **evidence** or **uncertainty** is flagged.
|
||||
|
||||
- [ ] Hypotheses are testable; diagnostics are actionable.
|
||||
|
||||
- [ ] Competence + collaboration hooks present (≤120 words total).
|
||||
|
||||
- [ ] Respect toggles; keep it concise.
|
||||
|
||||
- [ ] **Code path traced** (for software investigations).
|
||||
|
||||
- [ ] **Evidence validated** against actual code execution.
|
||||
|
||||
---
|
||||
|
||||
## Optional Globs (examples)
|
||||
|
||||
> Uncomment `globs` in the header if you want auto-attach behavior.
|
||||
|
||||
- `src/platforms/**`, `src/services/**` —
|
||||
|
||||
attach during service/feature investigations
|
||||
|
||||
- `docs/adr/**` — attach when editing ADRs
|
||||
|
||||
## Referenced Files
|
||||
|
||||
- Consider including templates as context: `@adr_template.mdc`,
|
||||
|
||||
`@investigation_report_example.mdc`
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Investigation
|
||||
|
||||
- [ ] **Problem Definition**: Clearly define the research question or issue
|
||||
- [ ] **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