xls_doc/docs/superpowers/plans/2026-06-18-docfill-p0.7-errors-logs.md

Docfill P0.7 Errors And Logs Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make failures easier for digital employees and humans to classify without turning docfill into a logging platform.

Architecture: Add a small AppError type in the internal package with code, hint, and context. Keep CLI formatting in cmd/docfill; add only one runtime logging switch, --verbose, which writes step logs to stderr.

Tech Stack: Go standard errors, existing CLI flag parsing, existing tests.

---

Task 1: Error Contract

Files:

• Create: internal/docfill/errors.go

• Modify: internal/docfill/p0_test.go

• Modify: cmd/docfill/main_test.go

• Add tests for coded missing-field and output-exists failures.

• Add tests for CLI stderr formatting with [CODE], hint:, and context:.

Task 2: Error Classification

Files:

• Modify: internal/docfill/docfill.go

• Create: internal/docfill/errors.go

• Classify config read, config parse, config validate, data Excel, data SQLite, template, output, and unresolved-placeholder failures where they already occur.

• Keep existing return signatures.

Task 3: Verbose Logs

Files:

• Modify: internal/docfill/docfill.go

• Modify: cmd/docfill/main.go

• Modify: cmd/docfill/main_test.go

• Add RunOptions.Logf.

• Add --verbose to docfill run.

• Log only config load, data read summary, and per-row output path.

Task 4: Docs And Verification

Files:

• Modify: README.md

• Modify: docs/digital-employee-runbook.md

• Document error shape and --verbose.

• Run go test -count=1 ./....

• Run bash scripts/smoke.sh.

• Run bash scripts/build.sh.