# Research Phase (Step 2.5)

Optional phase between Discovery and UI Design. Launches `senior-researcher`
agent to gather best practices, architectural patterns, or regulatory guidance
for complex/novel features.

---

## Trigger Evaluation

Evaluate research need when comprehension reaches **~75%** of non-test
dimensions covered. The discovery model has **COMPREHENSION_DIMENSION_COUNT = 11**
dimensions (0–10). Dimension 10 (Test strategy) is the single test dimension;
the remaining 10 are non-test. The 75% threshold is therefore **8/10 non-test
dimensions covered**. This allows background research to run while the last
discovery questions are being asked.

<!-- COMPREHENSION_DIMENSION_COUNT = 11 (dims 0-10); non-test = 10 (dims 0-9);
     75% threshold = 8 non-test dims covered. Update this constant if discovery-phase.md
     adds or removes dimensions. -->

### Complexity Signals

Scan discovery answers and codebase-architect findings for these signals:

| # | Signal | Example |
|---|--------|---------|
| S1 | Algorithm/pattern not in codebase | Recommendation engine, ranking algorithm, scoring system, ML pipeline |
| S2 | Regulatory/compliance requirement | GDPR consent, PCI-DSS, accessibility WCAG, food allergen regulations |
| S3 | External service/API never integrated | New payment provider, new SMS gateway, new OCR service |
| S4 | UX pattern not in the app | Drag-and-drop, real-time collaboration, complex data visualization |
| S5 | User explicitly signaled uncertainty **about a TECHNICAL or ARCHITECTURAL topic** (not naming/wording/preferences) | "non so come implementare X", "best practice per Y", "come fanno gli altri con Z", "devo capire quale approccio" |
| S6 | Architecture decision with multiple valid approaches | Polling vs WebSocket, CQRS vs simple CRUD, edge vs server |

### Confidence Classification

| Confidence | Condition | Action |
|------------|-----------|--------|
| **ALTA** | 2+ signals match, OR S2 (regulatory) matches alone, OR S5 (user uncertainty) matches alone **on a TECHNICAL/ARCHITECTURAL topic** | Launch research **in background immediately** — no user prompt |
| **MEDIA** | Exactly 1 non-S2/S5 signal matches | Ask user at discovery exit |
| **NESSUNA** | No signals match | Skip research, proceed to next phase |

---

## Research Execution

### HIGH Confidence — Background Auto-Launch

Trigger as soon as confidence is HIGH (typically at ~75% comprehension).

1. **Identify research topics** from the matching signals. Formulate 1-3
   specific research questions. Build the stack signature dynamically from
   `baldart.config.yml`:

   ```
   stack_signature = "{{stack.framework}} + {{stack.database}} + {{stack.auth_provider}}"
   # Examples it might resolve to:
   #   "nextjs + firestore + firebase-auth"
   #   "remix + supabase + supabase-auth"
   #   "sveltekit + postgres + lucia"
   # If any segment is empty, omit it from the signature.
   ```

   Examples of research questions (substitute {stack_signature} at runtime):
   - S1: "Best practices for implementing [pattern] on a {stack_signature} stack"
   - S2: "Regulatory requirements for [topic] in {{identity.jurisdiction}} (jurisdiction), implementation checklist"
     <!-- identity.jurisdiction is not a standard config key; if absent, ASK the user: "Which country/jurisdiction does this feature target?" and persist the answer as a note in the state file. identity.language (BCP-47 tag) is NOT a jurisdiction name. -->
   - S3: "Integration patterns for [service], comparison of approaches, gotchas"
   - S4: "UX best practices for [pattern], accessibility considerations, mobile"
   - S6: "Trade-offs of [approach A] vs [approach B] for [use case]"

2. **Launch `senior-researcher` agent in background via Task tool:**

   > **Background execution constraint**: When run in background, the
   > senior-researcher agent MUST skip its FIRST MESSAGE TEMPLATE preamble
   > (clarifying questions / search-plan acknowledgment loop) because no user
   > is available to respond. The prompt below MUST include the explicit
   > `BACKGROUND_RUN=true` directive so the agent knows to begin research
   > immediately. Add this as the first line of the prompt.

   ```
   Task tool:
     subagent_type: "senior-researcher"
     run_in_background: true
     prompt: |
       BACKGROUND_RUN=true — skip the FIRST MESSAGE TEMPLATE preamble entirely.
       Begin research immediately without waiting for acknowledgment.

       Research the following topics for a PRD we're writing for feature
       '<slug>'. Context: <1-2 line feature summary>.

       Project stack (from baldart.config.yml):
       - framework: {{stack.framework or 'unspecified'}}
       - database: {{stack.database or 'unspecified'}}
       - auth_provider: {{stack.auth_provider or 'unspecified'}}
       - deployment: {{stack.deployment or 'unspecified'}}

       Research questions:
       1. <question>
       2. <question>

       For each topic, provide:
       - Summary of best practices (with sources)
       - Recommended approach for the project stack above
       - Key gotchas or anti-patterns to avoid
       - If applicable: regulatory checklist or compliance requirements

       OUTPUT CONTRACT (mandatory):
       Write your complete research report to the file:
         ${paths.prd_dir}/<slug>/research-<slug>-<session-id>.md
       where <session-id> is a short UUID you generate at start.
       Log the exact output path as the FIRST line of your report:
         RESEARCH_OUTPUT_PATH: <full path>
       This path is how the PRD orchestrator will read your findings.
       Be concise but thorough.
   ```

3. **Continue discovery** — do NOT wait for the researcher. Ask remaining
   questions normally. The researcher runs in parallel.

4. **Log in state file** under `## Research`:
   ```
   Research: LAUNCHED (background)
   Confidence: ALTA
   Signals: S1 (pattern X), S5 (user said "non so come")
   Topics: [list]
   Status: in-progress
   LaunchTime: <ISO-8601 timestamp>
   ResearchOutputPath: (populated by researcher — checked at discovery exit)
   ```

5. **At discovery exit**, check if researcher has returned:
   - **Returned (output file exists)**: process findings (see "Processing Findings" below).
   - **Not returned yet (output file absent, status in-progress)**: inform user
     and wait up to **10 minutes** from the launch time recorded in the state file.
     Display waiting message:
     ```
     Discovery completata. La ricerca sulle best practice e ancora in corso,
     aspetto i risultati prima di procedere.
     ```
   - **Timed out (output file absent after 10-minute window)**: record
     `Status: timed-out` in state file and surface:
     ```
     La ricerca in background non ha restituito risultati entro il tempo atteso.
     Opzioni:
     A) Procedi senza ricerca (i risultati potrebbero essere parziali)
     B) Riprova a lanciare la ricerca in foreground (l'utente aspetta)
     ```
     **STOP.** Wait for user response. If A: mark `Status: timed-out`, proceed.
     If B: launch foreground (see MEDIUM path below) and set `Status: in-progress`.
   - **Failed (agent returned error)**: record `Status: failed` in state file and
     surface the same A/B choice as the timed-out case above.

### MEDIUM Confidence — Ask User

> **Guard**: Only fire this prompt when state file `Status` is blank/absent (not
> yet asked). After presenting the question, immediately set `Status: asked` in
> the state file. This prevents the question from being re-presented on
> context-compression resume or multi-turn re-evaluation.

At discovery exit (comprehension >= 99%), before proceeding to next phase:

```
### Ricerca Best Practice

La feature tocca **<matched signal description>**, un'area dove una ricerca
sulle best practice potrebbe migliorare la qualita del PRD.

Vuoi che lanci una ricerca su:
- <topic 1>
- <topic 2>

Questo aggiunge qualche minuto ma produce decisioni piu informate.

**A)** Si, lancia la ricerca <- consigliato
**B)** No, procedi direttamente
```

<!-- [CALIBRATION-NEEDED: foreground senior-researcher run time — empirically 5-15 min
     depending on tool latency and search depth; update the user-facing estimate once
     measured across representative PRD sessions.] -->

**STOP.** Wait for user response.

- If **A**: launch `senior-researcher` via Task tool in **foreground** (user is
  waiting; do NOT use `run_in_background: true`). Include `BACKGROUND_RUN=false`
  as the first line of the prompt so the agent follows its normal preamble flow.
  Log `Status: in-progress` in state file.

  **STOP.** Wait for the foreground Task tool to return. Do NOT continue to the
  next phase or issue additional tool calls until findings are returned.

  When the Task tool returns: verify the output file exists at the path logged by
  the researcher, then process findings (see "Processing Findings" below).
- If **B**: mark research as "skipped" in state file. Proceed to next phase.

---

## Processing Findings

When `senior-researcher` returns:

1. **Store findings** in state file under `## Research Findings`:
   ```
   ## Research Findings

   Source: senior-researcher agent (<date>)
   Topics researched: [list]

   ### Topic 1: <title>
   **Best practice**: <summary>
   **Recommended approach**: <for our stack>
   **Gotchas**: <anti-patterns to avoid>
   **Sources**: <references>

   ### Topic 2: <title>
   ...
   ```

2. **Evaluate if findings reveal gaps** in the discovery:
   - Do the findings introduce new dimensions or considerations NOT covered
     by existing discovery answers?
   - Do the findings contradict or significantly nuance any user decisions?
   - Do the findings require new data model fields, API endpoints, or UI
     elements not previously discussed?

3. **If gaps exist — extend discovery:**
   Present research-driven follow-up questions to the user. Use the same
   discovery question format (one question, STOP, wait):

   ```
   ### Domanda Extra (da ricerca) — <topic>

   La ricerca ha evidenziato che [finding summary].
   Questo impatta la nostra feature perche [impact].

   [Question to resolve the gap]

   **Raccomandazione**: **[Option]** (basata sulla ricerca)
   > [Rationale from research findings]

   **Alternative**:
   - **A)** [Research-recommended] <- consigliato (da ricerca)
   - **B)** [Alternative]
   ```

   **STOP.** Wait for user response. Update discovery log and state file.
   Repeat for each gap. These extra questions do NOT count toward the
   original 9 dimensions — they are logged separately as "research-driven".

4. **If no gaps**: summarize findings briefly and proceed.
   ```
   La ricerca conferma l'approccio emerso dalla discovery. Punti chiave:
   - [key finding 1]
   - [key finding 2]

   Procedo alla fase successiva.
   ```

---

## State File Updates

The research phase adds/updates these sections in the state file:

```markdown
## Research

Confidence: ALTA | MEDIA | NESSUNA
Signals: [matched signals]
Status: launched | in-progress | asked | completed | skipped | timed-out | failed
ResearchOutputPath: <path written by researcher, or empty>
Topics: [research questions]

## Research Findings

[populated when researcher returns — see format above]

## Research-Driven Discovery

[any follow-up questions/answers triggered by findings]
```

---

## Context Recovery — Resuming with In-Progress Research

When **Step 0 (Context Recovery)** in `discovery-phase.md` finds `Status: in-progress`
in the `## Research` section of the state file, apply this resolution logic:

1. **Check for the output file**: read `ResearchOutputPath` from the state file.
   - If the path is populated and the file exists → researcher already completed.
     Set `Status: completed`. Process findings normally (see "Processing Findings").
   - If the path is empty or the file does not exist → researcher did not complete
     before the previous session ended.

2. **If researcher did not complete**: surface to the user:
   ```
   La ricerca precedentemente lanciata non ha prodotto risultati (sessione
   interrotta). Opzioni:
   A) Rilancia la ricerca in foreground ora
   B) Procedi senza ricerca
   ```
   **STOP.** Wait for user response. Set `Status: failed` if B, or re-launch
   foreground (MEDIUM path) if A.

3. **Never silently proceed with `Status: in-progress`** — an unresolved
   in-progress state means either findings are available and unread, or
   the background run was lost. Always resolve explicitly.

---

## Integration with PRD Writing

During Step 4 (PRD Writing), if `## Research Findings` is populated:

- Reference findings in relevant PRD sections (data model, API, edge cases)
- Cite best practices in the "Rationale" or "Design Decisions" sections
- Include anti-patterns in the "Edge cases and failure modes" table
- If regulatory: add compliance checklist as a dedicated PRD section
