# 06 — Analysis Method

This file defines the method used for this research pack and how future reviewers should extend it. The goal is to prevent two common mistakes:

1. reading a paper as abstract inspiration without grounding it in current code,
2. reviewing only the currently active wave while missing the whole project direction.

## Scope Model

Analyze TheRoad-I1 as a long-form visual storytelling system with five interacting layers:

```mermaid
flowchart TD
  A[Research layer<br/>papers and benchmarks]
  B[Pipeline layer<br/>StepRunner / manifest / checkpoints]
  C[Contract layer<br/>schemas / helpers / RenderPromptCard]
  D[Prompt layer<br/>active prompt packs]
  E[Runtime evidence layer<br/>images / refs / validators / memory]

  A --> B
  B --> C
  C --> D
  D --> E
  E --> A
```

Every recommendation should touch at least two layers. A recommendation that only says "make the prompt better" is too weak. A recommendation that only adds code without prompt/schema/version implications is also incomplete.

## Research Reading Method

For each paper:

1. Identify the unit of memory:
   - character,
   - prop,
   - background/location,
   - frame/keyframe,
   - global plan,
   - latent/embedding.

2. Identify the update loop:
   - before generation only,
   - after each shot,
   - after each scene,
   - static reference only,
   - dynamic memory bank.

3. Identify the evaluation layer:
   - automatic metrics,
   - VLM judge,
   - human preference,
   - benchmark dataset,
   - no strong eval.

4. Ask whether the idea maps to TheRoad-I1 as:
   - already implemented,
   - partially implemented,
   - missing but useful,
   - not worth adopting.

## Code Audit Method

Use live-code evidence, not memory-only summaries.

Recommended grep pass:

```bash
rg -n "RenderPromptCard|render_prompt_card|visible_entities|reference|background_binding|subject_reference_policy|gaze_direction_kind|subject_state|gaze_target|STATE_DESCRIPTIONS|IMMOBILIZED_GAZE|verify_completion|schema_version|prompt_dependency" \
  backend/app prompts/_base docs/superpowers
```

Then inspect:

- `backend/app/core/step_manifest.py`
- `backend/app/core/version_registry.py`
- `backend/app/modules/prompt_loader.py`
- `backend/app/core/steps/render_prompt_card.py`
- `backend/app/core/steps/detail_steps.py`
- `backend/app/services/scene_reference_service.py`
- `backend/app/core/steps/image_steps.py`
- active prompt packs under:
  - `prompts/_base/shot_staging/<latest>/`
  - `prompts/_base/scene_detail/<latest>/`
  - `prompts/_base/scene_extractor_v2/<latest>/`

## Prompt Audit Method

For each prompt pack:

1. Confirm latest directory by numeric version sort.
2. Confirm stem pack completeness if the loader can pick stems independently.
3. Identify whether the prompt:
   - emits structured fields,
   - consumes structured fields,
   - still uses prose-only rules,
   - includes scenario-specific examples,
   - includes noun lists that can become logic.
4. Check whether code consumes the same field names as the prompt/schema emits.
5. Add a residue gate if a field is deprecated.

## Architecture Decision Method

Use this decision table before adopting a paper idea.

| Question | If yes | If no |
|---|---|---|
| Does it introduce durable state? | require schema/version/provenance | keep it local or prompt-only |
| Does code need to judge semantics? | push judgment to LLM/VLM structured emit | helper can validate closed-world shape |
| Does it affect prompt packs? | bump prompt/version and add loader tests | avoid prompt churn |
| Does it affect generated images? | add VLM/human eval path | unit tests may be enough |
| Does it cross scenes? | use StoryWorldMemory/SceneContinuityPlan | RenderPromptCard may be enough |

## Whole-Project Analysis Checklist

Use this checklist for future research-to-project reviews:

- Research contribution summarized.
- Related work compared.
- Current pipeline mapped.
- Active prompt packs inspected.
- Version/manifest sync checked.
- Existing contracts identified.
- Legacy semantic string debt identified.
- Runtime reference/memory flow traced.
- Evaluation gap identified.
- Development sequence proposed.
- Failure modes and controls listed.

## How To Avoid Over-Engineering

Adopt research ideas in this order:

1. read-only memory index,
2. dry-run retrieval logs,
3. post-generation observer metadata,
4. gated reference retrieval,
5. optional candidate QA,
6. only then expensive multi-candidate generation.

Do not start with VAE embeddings or a large multi-agent rewrite. The project's biggest current asset is deterministic contract discipline. Preserve that.

## How To Avoid Under-Engineering

Do not reduce the research lesson to "make prompts more detailed." The recurring failure pattern across the papers is not insufficient prompt length. It is missing world state and weak memory update.

Minimum serious implementation:

- typed memory item schema,
- source provenance,
- generated-image observation,
- retrieval policy,
- continuity evaluator.