chore: unify and centralize agent configuration in .agent/

2 files changed, 70 insertions, 0 deletions

diff --git a/bug-manager/SKILL.md b/bug-manager/SKILL.md
new file mode 100644
index 0000000..bf48357
--- /dev/null
+++ b/bug-manager/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: bug-manager
+description: Manage, list, and resolve production bugs using custom project scripts. Use when investigating reported errors, viewing production logs, or marking bugs as resolved in the dashboard's database.
+---
+
+# Bug Manager
+
+This skill formalizes the workflow for handling production bugs in the `doot` project.
+
+## Workflow
+
+### 1. Identify Bugs
+- Run `./scripts/bugs` to list currently open production bugs.
+- Each bug has an `id`, a `description`, and a `created_at` timestamp.
+
+### 2. Diagnose with Logs
+- Use `./scripts/logs` to investigate.
+- For recent errors: `./scripts/logs -n 100`
+- To filter for errors: `./scripts/logs --grep "error"`
+- Refer to [references/bug-triage.md](references/bug-triage.md) for common error patterns.
+
+### 3. Fix and Verify
+- Implement a reproduction test locally.
+- Apply the fix.
+- Deploy via `./scripts/deploy`.
+
+### 4. Resolve
+- Mark the bug as resolved using `./scripts/resolve-bug <id>`.
+- This script also displays the bug description before deletion for confirmation.
+
+## Quick Start
+- "List all production bugs" -> `./scripts/bugs`
+- "Show me the last 50 lines of production logs" -> `./scripts/logs -n 50`
+- "Mark bug #12 as resolved" -> `./scripts/resolve-bug 12`
diff --git a/bug-manager/references/bug-triage.md b/bug-manager/references/bug-triage.md
new file mode 100644
index 0000000..45fe6cf
--- /dev/null
+++ b/bug-manager/references/bug-triage.md
@@ -0,0 +1,36 @@
+# Bug Triage & Resolution Guide
+
+This reference provides a structured approach to managing production bugs using the `doot` project's custom scripts.
+
+## 1. Listing Bugs
+Use `./scripts/bugs` to list all currently open bugs from the production database.
+Bugs are stored in the `bugs` table with `id`, `description`, and `created_at`.
+
+## 2. Investigating Logs
+When a bug is reported, always check the production logs first.
+Use `./scripts/logs` with various flags:
+- `scripts/logs -n 200`: View the last 200 lines.
+- `scripts/logs --since "1 hour ago"`: View recent logs.
+- `scripts/logs --grep "error"`: Search for specific error patterns.
+- `scripts/logs -f`: Follow logs in real-time (useful for reproduction).
+
+### Common Error Patterns
+- **Database Locked:** SQLite `database is locked` errors usually indicate concurrent writes or long-running transactions.
+- **Unauthorized:** Check for `401` or `403` status codes in API clients (Todoist, Trello, etc.).
+- **Template Errors:** Look for `template: ...: executing ...: nil pointer evaluating ...` which indicates missing data in the renderer.
+
+## 3. Reproduction
+Before applying a fix, attempt to reproduce the bug locally.
+1. Use `go test ./...` to ensure the current state is stable.
+2. Create a new test case in the relevant `*_test.go` file that specifically triggers the reported bug.
+3. Confirm the test fails.
+
+## 4. Resolution
+Once a fix is implemented and verified locally:
+1. Deploy the fix using `./scripts/deploy`.
+2. Verify the fix in production if possible (e.g., by checking logs).
+3. Use `./scripts/resolve-bug <id>` to mark the bug as resolved in the production database.
+
+## 5. Verification
+After resolving, run `./scripts/bugs` again to ensure it no longer appears in the list.
+Update `SESSION_STATE.md` to reflect the completed bug fix.