# Prompt Hygiene v1 Spec

Date: 2026-05-14

Scope: currently active file prompt packs under `prompts/_base` that contain
scenario-specific examples, overly concrete synthetic examples, or duplicated
domain nomenclature. This is a small prompt cleanup track. It does not migrate
production regex routing; that is tracked in
`2026-05-14-semantic-string-routing-debt-map.md`.

## 1. Audit Boundary

Included:

- Latest prompt directories under `prompts/_base`.
- `*.md`, `*.txt`, and `*.json` files in those latest prompt directories.
- Scenario names, project-like IDs, concrete example scenes, and prompt-side
  closed lists that duplicate a better SOT.

Excluded:

- Legacy prompt directories that are not the latest file fallback.
- Runtime code regex/token debt.
- DB prompt rows, except as a mandatory pre-implementation verification note.

Important loader caveat:

- `backend/app/modules/prompt_loader.py:1-5` says DB rows are loaded before
  file fallback.
- `prompt_loader.py:7-14` says file fallback picks the latest directory per
  stem, not necessarily a whole module version pack.
- `prompt_loader.py:30-33` says DB-aware callers can bypass strict file pack
  checks.
- `prompt_loader.py:108-137` is the actual prompt load path.

Therefore a file prompt hygiene patch must verify whether the affected module is
file-only or DB-overridden before claiming production effect.

## 2. Verification Passes Performed

- Regenerated latest prompt directory list from `prompts/_base`.
  - Latest directories: 58.
  - Latest prompt/schema files scanned: 177.
- Direct search for known scenario-like or high-specificity terms:
  - `은성`, `ZRBB`, `동녘`, `강의원`, `캡슐속`, `주인공`, `청록색`
  - `compact room`, `wet floor`, `shared bench`, `Figure A`, `Figure B`
  - `Korean police`, `Joseon`, `Korean-style`, `tiled-roof`
  - transformation/domain terms such as `요괴`, `구미호`, `이무기`,
    `뱀파이어`, `좀비`, `망령`, `빙의`, `원격 조종`, `아바타`
- Re-read the active prompt files containing hits.

## 3. Classification

P0: confirmed scenario/project leak. Must be removed before relying on prompt
pack generality.

P1: not a screenplay leak, but too concrete or too domain-specific. Should be
genericized in a hygiene patch.

P2: acceptable generic example or intentional SOT. Keep, but document the owner.

## 4. P0 Confirmed Scenario/Project Leaks

### P0-1. `entity_extraction/v7/chunk_system.md`

Evidence:

- `prompts/_base/entity_extraction/v7/chunk_system.md:24`
  contains `예: 은성<->ZRBB51`.

Why it is a problem:

- `은성` reads as a real character name.
- `ZRBB51` reads as a project/scenario-specific code.
- The line is in a general relationship extraction prompt, so it can prime the
  model toward a particular story style.

Fix:

- Create a new prompt version for `entity_extraction`.
- Replace with a generic structural example:
  - `예: <character_id 또는 character_name> <-> <signature_prop_id>`
  - or `예: C## <-> P##` if the prompt context already accepts short IDs.
- Do not introduce new story nouns.

### P0-2. `scene_extractor_v2/system.md` possession example

Evidence:

- `prompts/_base/scene_extractor_v2/17.202604101200/system.md:59-60`
  says remote-control/access characters are excluded and gives the example
  `"동녘(강의원)"`.

Why it is a problem:

- The example encodes concrete names.
- The underlying rule is valid, but the example should be generic.

Fix:

- New `scene_extractor_v2` prompt version.
- Replace with:
  - `"<visible_body_name>(<remote_identity_name>)" -> only the visible body is present; the remote identity is elsewhere`
- Add a pointer to `visual_world_rules.rules[].rule_type=possession` if the
  prompt receives that context.

### P0-3. `scene_extractor_v2/system.md` container example

Evidence:

- `prompts/_base/scene_extractor_v2/17.202604101200/system.md:63`
  contains `"캡슐속 남자들"`.
- `prompts/_base/scene_extractor_v2/17.202604101200/turn_scene_detail.md:108`
  repeats a similar capsule/helicopter example.

Why it is a problem:

- The rule is valid: do not include objects that appear only as modifiers.
- The example is too scene-shaped and can bias extraction toward a specific
  sci-fi/action setup.

Fix:

- Replace with:
  - `"<container descriptor> inside people" / "<people described only through a container modifier>"`
  - Korean equivalent: `"<container> 안의 인물들"이 실제 현장에 없으면 제외`
- Keep the rule, remove the capsule/helicopter specificity.

## 5. P1 Over-Specific Active Prompt Examples

### P1-1. Region/era examples in `scene_extractor_v2/turn_scene_detail.md`

Evidence:

- `prompts/_base/scene_extractor_v2/17.202604101200/turn_scene_detail.md:83-85`
  uses `Korean police officer`, `Korean-style apartment`,
  `Korean convenience store`, `Joseon-era nobleman`, and
  `tiled-roof wooden structure`.

Why it is a problem:

- These are not screenplay leaks by themselves.
- But they hard-prime Korean/Joseon phrasing in a generic extraction prompt.

Fix:

- Replace with placeholders tied to source context:
  - `<region-derived demonym> police officer`
  - `<region-style apartment>`
  - `<region-style convenience store>`
  - `<era-derived noble role>`
  - `<era-appropriate roofed wooden structure>`
- Keep the principle: do not strip culturally meaningful region/era cues.

### P1-2. `t2i_visual_converter` example is too scene-toned

Evidence:

- `prompts/_base/t2i_visual_converter/v3/system.md:19`
  contains `[주인공]이 투명 벽 너머로 남자를 올려다본다, 청록색 발광, 미디엄 숏`.

Why it is a problem:

- `주인공` is generic, but the whole example has a specific sci-fi/lighting
  tone.
- It can bias visual conversion examples toward transparent wall / teal glow.

Fix:

- Replace with:
  - `[primary character] looks toward [secondary visible target], <lighting cue>, <shot scale>`
- Avoid concrete color/prop unless the example is explicitly about preserving a
  source-specified color/prop.

### P1-3. `t2i_review/scene_system.md` synthetic examples are too concrete

Evidence:

- `prompts/_base/t2i_review/3.202605121200/scene_system.md:45-47`
  uses `compact room`, `existing tabletop`, and a full close-framing rewrite.
- `scene_system.md:61-63` uses `wet floor planks visible behind subject's hands`.
- `scene_system.md:69-78` uses `Figure A`, `Figure B`, bench, shared bench,
  and a small object being offered.
- `scene_system.md:87-90` instructs exact substring `target -> suggestion`
  replacement.

Why it is a problem:

- The comments say "synthetic placeholder", but the examples are long enough to
  become style/scene priors.
- They also mirror code-side blind substring mutation in
  `backend/app/modules/pipeline/t2i_review.py:383-403` and `:407-451`.

Fix:

- Keep issue-type definitions.
- Replace concrete examples with abstract placeholders:
  - `<existing background object>`
  - `<frame-edge surface>`
  - `<shared support surface>`
  - `<foreground actor>` / `<background actor>`
- Do not add more exact physical examples.
- Long-term: replace target/suggestion mutation with structured patch IDs or
  regeneration diagnostics.

## 6. Domain Nomenclature Centralization

These are not simple "delete all" items. They are valid genre/world-building
concepts but should be centralized.

### Current distributed sites

- `prompts/_base/entity_all/4.202603310100/character.md:26-31`
  mentions human/non-human transformation, possession/fusion, imugi, gumiho,
  monsterization, vampire.
- `prompts/_base/entity_character_list/2.202605011057/system.md:10`
  lists human, monster, animal, robot, alien-like entities.
- `prompts/_base/outlook_extractor/11.202603311724/phase1.md:24`
  mentions humanoid monster, vampire, zombie.
- `prompts/_base/entity_relation/2.202603301800/system.md:11-13,30-37`
  mentions human to monster/ghost transformations.
- `prompts/_base/visual_world_rules/6.202605021400/system.md:30-36,51`
  already defines the better conceptual SOT:
  `possession`, `transformation`, `ghost`, `projection`, `superpower`,
  `body_deformation`, `time_period`, `costume`, `technology`, `other`.

Assessment:

- `visual_world_rules` is the right owner.
- Other prompts should not maintain their own mythology-specific taxonomy.

Fix:

- In non-owner prompts, replace long specific lists with:
  - "Follow `visual_world_rules.rules[]` for possession, transformation,
    ghost/projection, supernatural body changes, era/costume/technology rules."
- Keep only one or two generic placeholders if necessary.
- Do not remove the ability to handle Korean fantasy/supernatural material; just
  move that logic to the central rule owner.

## 7. LLM-Side String Heuristics To Track But Not Fix In v1

These are prompt-side classifier instructions that pair with code-side debt.
They should remain in the debt map/backlog, not the hygiene v1 patch.

### 7.1 `shot_director`

Evidence:

- `prompts/_base/shot_director/5.202605131800/system.md:29-45` instructs the
  model with gaze, close-up, off-camera, and blocking phrase patterns.

Why not in v1:

- This is not a simple scenario contamination cleanup.
- It must be solved with structured visibility/offscreen SOT and code changes.

### 7.2 `scene_detail_owned_judge`

Evidence:

- `prompts/_base/scene_detail_owned_judge/3.202605051746/system.md:18-61`
  relies on verb and phrase classes for redraw/anchor judgment.

Why not in v1:

- It is a semantic classifier design issue, not prompt leak cleanup.

### 7.3 `t2i_review`

Evidence:

- `prompts/_base/t2i_review/3.202605121200/scene_system.md:31-91` defines
  phrase-detection issue types and exact target/suggestion mutation behavior.

Why not in v1:

- v1 can genericize examples.
- Replacement of mutation strategy requires code and schema changes.

## 8. Required Pre-Implementation Checks

Before editing any prompt files:

1. DB override check
   - For each affected `(module, stem)`, query whether an active DB row exists.
   - If DB row exists, file-only prompt version will not affect runtime.

2. Prompt versioning check
   - Do not overwrite existing prompt directories.
   - Create new version directories following the project convention.

3. Code pin check
   - Some steps pin prompt versions or use constants for checkpoint invalidation.
   - For each affected module, search production code for prompt version constants
     before claiming "code changes 0".

4. Active pack check
   - After new prompt directories are created, call prompt source/effective source
     tooling or equivalent to prove the new version is active.

5. Residue grep
   - After cleanup, grep active prompt files for:
     - `은성`
     - `ZRBB`
     - `동녘`
     - `강의원`
     - `캡슐속`
     - `청록색 발광`
     - `compact room`
     - `wet floor planks`
     - `shared bench`

## 9. Recommended Patch Shape

### Patch H1. Active prompt hygiene

Scope:

- `entity_extraction`
- `scene_extractor_v2`
- `t2i_visual_converter`
- `t2i_review`

Actions:

- Create new prompt directories.
- Replace P0/P1 examples with placeholders.
- Do not change schemas unless the prompt version requires pack completeness.
- Run residue grep.

### Patch H2. Visual-world nomenclature centralization

Scope:

- `entity_all`
- `entity_character_list`
- `outlook_extractor`
- `entity_relation`
- `visual_world_rules`

Actions:

- Keep `visual_world_rules` as owner.
- Update other prompts to refer to it.
- Avoid hardcoding mythology lists in downstream prompts.

### Patch H3. Prompt-side heuristic redesign

Scope:

- `shot_director`
- `scene_detail_owned_judge`
- `t2i_review`

Actions:

- Not part of v1.
- Requires structured SOT/code migration specs.

## 10. Do Not Do

- Do not edit legacy prompt directories.
- Do not overwrite existing prompt files in-place.
- Do not delete valid supernatural/transformation capability.
- Do not replace concrete examples with a different concrete scene.
- Do not combine prompt hygiene with code-side regex migration.

## 11. Completion Criteria For Hygiene v1

Hygiene v1 is complete only when:

- P0 leaks are gone from active prompts.
- P1 concrete examples are replaced with placeholders.
- Domain nomenclature has one owner or is explicitly deferred to H2.
- DB/file active source is verified.
- Residue grep on active prompt pack is clean for the listed leak terms.