# 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`.