ui/.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)