diff --git a/docs/step1.md b/docs/step1.md index 3adc083..c9693c2 100644 --- a/docs/step1.md +++ b/docs/step1.md @@ -1,7 +1,3 @@ -I now have a complete understanding of all the constraints. Here is the detailed implementation plan for Step 1: - ---- - # Step 1 Implementation Plan: `config.py` + `models.py` + `db.py` ## Purpose @@ -573,4 +569,4 @@ Explicitly out of scope to prevent scope creep: --- -This plan produces a fully tested, importable data foundation. Every subsequent step imports from `transcription.config`, `transcription.models`, and `transcription.db` without modification. When you're ready, switch to **Agent mode** and I'll implement it. \ No newline at end of file +This plan produces a fully tested, importable data foundation. Every subsequent step imports from `transcription.config`, `transcription.models`, and `transcription.db` without modification. \ No newline at end of file diff --git a/docs/step2.md b/docs/step2.md new file mode 100644 index 0000000..99d6ffa --- /dev/null +++ b/docs/step2.md @@ -0,0 +1,155 @@ +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