53 lines
1.9 KiB
Markdown
53 lines
1.9 KiB
Markdown
# 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`.
|