annotations/.cursor/skills/research/steps/00_project-integration.md

## Project Integration

### Prerequisite Guardrails (BLOCKING)

Before any research begins, verify the input context exists. **Do not proceed if guardrails fail.**

**Project mode:**
1. Check INPUT_DIR exists — **STOP if missing**, ask user to create it and provide problem files
2. Check `problem.md` in INPUT_DIR exists and is non-empty — **STOP if missing**
3. Check `restrictions.md` in INPUT_DIR exists and is non-empty — **STOP if missing**
4. Check `acceptance_criteria.md` in INPUT_DIR exists and is non-empty — **STOP if missing**
5. Check `input_data/` in INPUT_DIR exists and contains at least one file — **STOP if missing**
6. Read **all** files in INPUT_DIR to ground the investigation in the project context
7. Create OUTPUT_DIR and RESEARCH_DIR if they don't exist

**Standalone mode:**
1. Check INPUT_FILE exists and is non-empty — **STOP if missing**
2. Resolve BASE_DIR: use the caller-specified directory if provided; otherwise default to `_standalone/`
3. Resolve OUTPUT_DIR (`BASE_DIR/01_solution/`) and RESEARCH_DIR (`BASE_DIR/00_research/`)
4. Warn if no `restrictions.md` or `acceptance_criteria.md` were provided alongside INPUT_FILE — proceed if user confirms
5. Create BASE_DIR, OUTPUT_DIR, and RESEARCH_DIR if they don't exist

### Mode Detection

After guardrails pass, determine the execution mode:

1. Scan OUTPUT_DIR for files matching `solution_draft*.md`
2. **No matches found** → **Mode A: Initial Research**
3. **Matches found** → **Mode B: Solution Assessment** (use the highest-numbered draft as input)
4. **User override**: if the user explicitly says "research from scratch" or "initial research", force Mode A regardless of existing drafts

Inform the user which mode was detected and confirm before proceeding.

### Solution Draft Numbering

All final output is saved as `OUTPUT_DIR/solution_draft##.md` with a 2-digit zero-padded number:

1. Scan existing files in OUTPUT_DIR matching `solution_draft*.md`
2. Extract the highest existing number
3. Increment by 1
4. Zero-pad to 2 digits (e.g., `01`, `02`, ..., `10`, `11`)

Example: if `solution_draft01.md` through `solution_draft10.md` exist, the next output is `solution_draft11.md`.

### Working Directory & Intermediate Artifact Management

#### Directory Structure

At the start of research, **must** create a working directory under RESEARCH_DIR:

```
RESEARCH_DIR/
├── 00_ac_assessment.md            # Mode A Phase 1 output: AC & restrictions assessment
├── 00_question_decomposition.md   # Step 0-1 output
├── 01_source_registry.md          # Step 2 output: all consulted source links
├── 02_fact_cards.md               # Step 3 output: extracted facts
├── 03_comparison_framework.md     # Step 4 output: selected framework and populated data
├── 04_reasoning_chain.md          # Step 6 output: fact → conclusion reasoning
├── 05_validation_log.md           # Step 7 output: use-case validation results
├── 06_component_fit_matrix.md     # Step 7.5 output: component exact-fit gate
└── raw/                           # Raw source archive (optional)
    ├── source_1.md
    └── source_2.md
```

#### Splittable artifacts — Layout convention

The following three artifacts MAY equivalently be a **folder** of the same base name when the single-file form has grown unwieldy (typically ≳ 1000 lines or ≳ 200 KB):

- `01_source_registry.md` ↔ `01_source_registry/`
- `02_fact_cards.md` ↔ `02_fact_cards/`
- `06_component_fit_matrix.md` ↔ `06_component_fit_matrix/`

When using the folder form:

- Place a `00_summary.md` index file at the folder root with a short common summary table and the cross-cutting status the single-file form would have carried in its preamble.
- Split per-entry content into category files (e.g. one file per sub-question or per component): `SQ1_*.md`, `C1_*.md`, etc. Keep entry numbering global across the folder so cross-references like "Source #42" still resolve to exactly one place.
- Cross-references from outside the folder may point at either `01_source_registry/00_summary.md` (for the index) or directly at the relevant category file.

```
RESEARCH_DIR/01_source_registry/        # split form (when single-file is too large)
├── 00_summary.md                       # index + investigation status + compact source table
├── SQ1_existing_systems.md             # category file
├── SQ2_canonical_pipeline.md           # category file
├── C1_vio.md                           # per-component file
└── ...
```

Throughout the rest of this skill (other steps, references, templates), the singular `XX.md` form is used as a logical name; treat each occurrence as applying equally to the folder form when the artifact has been split.

### Save Timing & Content

| Step | Save immediately after completion | Filename |
|------|-----------------------------------|----------|
| Mode A Phase 1 | AC & restrictions assessment tables | `00_ac_assessment.md` |
| Step 0-1 | Question type classification + sub-question list | `00_question_decomposition.md` |
| Step 2 | Each consulted source link, tier, summary | `01_source_registry.md` *(splittable, see convention)* |
| Step 3 | Each fact card (statement + source + confidence) | `02_fact_cards.md` *(splittable, see convention)* |
| Step 4 | Selected comparison framework + initial population | `03_comparison_framework.md` |
| Step 6 | Reasoning process for each dimension | `04_reasoning_chain.md` |
| Step 7 | Validation scenarios + results + review checklist | `05_validation_log.md` |
| Step 7.5 | Component exact-fit gate and selection status | `06_component_fit_matrix.md` *(splittable, see convention)* |
| Step 8 | Complete solution draft | `OUTPUT_DIR/solution_draft##.md` |

### Save Principles

1. **Save immediately**: Write to the corresponding file as soon as a step is completed; don't wait until the end
2. **Incremental updates**: Same file can be updated multiple times; append or replace new content
3. **Preserve process**: Keep intermediate files even after their content is integrated into the final report
4. **Enable recovery**: If research is interrupted, progress can be recovered from intermediate files

### Output Files

**Required files** (automatically generated through the process):

| File | Content | When Generated |
|------|---------|----------------|
| `00_ac_assessment.md` | AC & restrictions assessment (Mode A only) | After Phase 1 completion |
| `00_question_decomposition.md` | Question type, sub-question list | After Step 0-1 completion |
| `01_source_registry.md` *(splittable)* | All source links and summaries | Continuously updated during Step 2 |
| `02_fact_cards.md` *(splittable)* | Extracted facts and sources | Continuously updated during Step 3 |
| `03_comparison_framework.md` | Selected framework and populated data | After Step 4 completion |
| `04_reasoning_chain.md` | Fact → conclusion reasoning | After Step 6 completion |
| `05_validation_log.md` | Use-case validation and review | After Step 7 completion |
| `06_component_fit_matrix.md` *(splittable)* | Exact-fit matrix for every proposed component/tool/pattern with status `Selected` / `Rejected` / `Experimental only` / `Needs user decision` | Before Step 8 deliverable formatting |
| `OUTPUT_DIR/solution_draft##.md` | Complete solution draft | After Step 8 completion |
| `OUTPUT_DIR/tech_stack.md` | Tech stack evaluation and decisions | After Phase 3 (optional) |
| `OUTPUT_DIR/security_analysis.md` | Threat model and security controls | After Phase 4 (optional) |

**Optional files**:
- `raw/*.md` - Raw source archives (saved when content is lengthy)