crowd-funder-for-time-pwa/.cursor/rules/development/research_diagnostic.mdc

---
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