project-docling-engineer

name: project-docling-engineer description: Engineer robust Python document-processing systems for this repository. Use when tasks involve Docling-first analysis, OCR/table fallback design, editable DOCX generation, RTL/LTR mixed text handling, project scaffolding, CI/tooling setup, or implementation planning and execution that must prioritize correctness, maintainability, and practical delivery.

Project Docling Engineer

Overview

Plan and implement production-grade changes for Python + Docling + DOCX workflows in this repo. Prioritize architecture clarity, testability, and staged delivery over quick but fragile code.

Workflow

1. Confirm target outcomes and acceptance criteria before writing code.
2. Inspect current state first (tree, rg, config, tests, CI).
3. Propose minimal viable architecture changes with explicit tradeoffs.
4. Implement in thin vertical slices:
   • keep stage boundaries clean (preprocess, analyze, render-docx, validate)
   • use interfaces/adapters for engines and fallbacks
   • keep IR stable and version-aware
5. Add verification with every slice:
   • unit tests for pure logic and schema
   • CLI smoke tests for orchestration
   • artifact checks for deterministic outputs
6. Report residual risks and clear next steps.

Implementation Rules

• Keep modules cohesive; avoid monolithic stage files.
• Preserve editability in DOCX output: prefer native paragraphs/tables/checkbox-like symbols before raster overlays.
• Preserve geometry explicitly in IR; avoid lossy implicit conversions.
• Treat mixed-direction text as first-class: store direction metadata on lines/spans/cells.
• Make fallback behavior explicit and observable in logs/metadata.
• Avoid hidden global state; pass context/config through stage boundaries.

Quality Gates

• Run lint/format/type/test before finalizing:
  • ruff check src tests
  • ruff format --check src tests
  • mypy src
  • pytest
• Run CLI smoke checks:
  • python -m docmirror --help
  • python -m docmirror run-all <sample.jpg> -o out
• Validate that logs and debug artifacts are generated in configured paths.

Use Bundled References

• For Docling integration details and option selection: read references/docling-implementation-guide.md.
• For engineering behavior and delivery checks: read references/engineering-checklist.md.
• For DOCX/RTL implementation notes: read references/docx-rtl-notes.md.

Use Bundled Script

• scripts/run_quality_gate.py runs the standard local quality checks in one command.

Output Expectations

• Deliver concrete code changes, validation evidence, and a short risk list.
• Do not stop at abstract advice when implementation is feasible.