transcription/docs/step2.md

Great—here’s a detailed implementation plan for Step 2 based on your docs and current project state.

Step 2 Goal

Implement the MVP prompt artifact system by creating a curated transcription prompt file:

• prompts/transcribe_document.md

This step primarily satisfies:

• REQ-12: prompts stored as individual Markdown artifacts
• MVP Feature 3: prompt-driven verbatim transcription behavior grounded in docs/Intent.md

---

Scope for Step 2

In scope

1. Create prompt artifact directory and first prompt file.
2. Encode transcription rules from docs/Intent.md into a model-facing prompt.
3. Define stable prompt structure so future revisions are easy to diff/review.
4. Add lightweight tests that validate artifact presence and baseline quality constraints.
5. Update docs/README references so Step 3 can consume prompt file directly.

Out of scope

• Provider integration logic (Step 3)
• Worker/job orchestration (Step 4)
• UI behavior (Step 5)

---

Proposed Deliverables

1. prompts/transcribe_document.md

   • production prompt text for historical document transcription

2. prompts/README.md (recommended)

   • conventions for prompt files, revision policy, naming

3. tests/test_prompts.py (recommended)

   • artifact existence + structure checks

4. Small docs update (README or docs reference)

   • indicate that prompts are file-based and loaded from PROMPT_DIR

---

Detailed Work Breakdown

1) Create prompt artifact folder and canonical file

• Add prompts/ at repo root.
• Add transcribe_document.md as the first curated artifact.
• Keep filename stable; this becomes the default in Step 3 unless overridden.

2) Author prompt content using a strict, sectioned format

Use section headers so future diffs are clean and policy changes are isolated.

Suggested sections:

1. Purpose

   • verbatim scholarly transcription of historical documents

2. Output requirements

   • plain text only
   • no summaries, no paraphrasing
   • preserve reading order and meaningful structure

3. Core fidelity rules

   • preserve original wording and punctuation
   • don’t silently normalize grammar/spelling
   • no invented content

4. Issue-handling rules (mapped from Intent table)

   • misspellings with [sic]
   • missing words with [word]
   • uncertainty with [guess?]
   • illegible with [illegible] / reason tags
   • crossed-out text as [deleted: ...]
   • inserted text as [inserted: ...]
   • superscripts handling guidance
   • non-text elements as [description]
   • marginalia format [written in left margin: ...]
   • line-break hyphen rejoin behavior
   • capitalization policy
   • hierarchical outline preservation (including unusual numbering)

5. Confidence/ambiguity policy

   • prefer explicit uncertainty markers over hallucination

6. Final self-checklist for model

   • did I preserve structure?
   • did I mark uncertain text?
   • did I avoid silent corrections?

3) Add prompt-library conventions (prompts/README.md)

Recommended conventions:

• one prompt per file
• snake_case names
• each file starts with purpose + behavior contract
• iterative edits, one prompt per PR where possible
• no secrets in prompt files

4) Add tests for prompt assets (tests/test_prompts.py)

Keep tests robust but not brittle.

Recommended tests:

1. test_prompt_file_exists
2. test_prompt_file_is_not_empty
3. test_prompt_mentions_verbatim_behavior
4. test_prompt_includes_uncertainty_and_illegible_markers
5. test_prompt_includes_deleted_and_inserted_conventions

Avoid exact full-text matching; verify key semantic anchors only.

5) Optional config alignment check

Current config already has:

• prompt_dir: Path = Path("./prompts")

In Step 2, ensure docs reflect this and that Step 3 will resolve:

• PROMPT_DIR / "transcribe_document.md"

---

Acceptance Criteria (Definition of Done)

Step 2 is complete when all are true:

1. prompts/transcribe_document.md exists and is committed.
2. Prompt includes all critical handling rules from docs/Intent.md.
3. Prompt is structured with stable section headings for future curation.
4. Prompt tests pass under uv run pytest -q.
5. Existing tests remain green (total suite still passes).
6. Docs indicate prompt artifact location and curation policy.

---

Risks and Mitigations

1. Risk: prompt too vague → hallucinated reconstructions

   • Mitigation: explicit uncertainty/illegible conventions and “no invention” rule.

2. Risk: prompt too rigid for mixed document types

   • Mitigation: include neutral defaults + clear annotation formats.

3. Risk: brittle tests block iterative prompt tuning

   • Mitigation: test semantic anchors, not exact wording.

---

Handoff to Step 3

After Step 2, Step 3 can immediately:

1. Load transcribe_document.md from PROMPT_DIR
2. Inject prompt into OpenRouter request
3. Start validating real transcription behavior with minimal glue code