From 8ef123393ab00780bdba360b41edc2fd8d742c24 Mon Sep 17 00:00:00 2001 From: Frank Schwenk Date: Thu, 16 Jul 2026 21:32:23 +0200 Subject: [PATCH] docs: sharpen verification, debug-loop, and subagent guidance Capture preferred away/E2E working style: real smoke over fake-done, defined debug-loop limit, wallclock note in handoff. Co-authored-by: Cursor --- AGENTS.md | 15 ++++++++++++++- BOUNDARIES.md | 2 +- USER.md | 3 ++- 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6905496..4e103ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -134,6 +134,12 @@ Fränky's bar is **pragmatic, not TDD-by-default** (`USER.md`: tests score 2/5). - Follow project `SOUL.md` if stricter (e.g. pytest before handoff) - Do not block small fixes on missing test infrastructure +### Verification (pragmatic) + +- If the project has a runnable stack (Compose, CLI, service): prefer a **real smoke / happy-path** before handoff — not “code looks fine” +- Waiting on slow builds or pipeline jobs is OK and preferred over fake-green +- Unit/integration tests still apply when a suite exists; smoke does not replace them, and they do not replace smoke when infra is the product + --- ## Commits & Issues @@ -159,9 +165,10 @@ Scratchpad — use for blocked tasks, session park, overnight-run status, handof | Task | Subagent | |------|----------| | Unknown codebase or many files to scan | **Explore** | +| Greenfield / large feature implementation | **generalPurpose** (parent keeps orchestrating deploy/ntfy) | | Browser / E2E / web UI | **Playwright** | | Broad research | **generalPurpose** or **Explore** | -| Shell / git batch ops | **shell** | +| Shell / git / sync / remote compose | **shell** | **Explore** for any project type when orientation is unclear — not only web. **Playwright** only when there is a web UI to test. @@ -200,9 +207,15 @@ See `INFRASTRUCTURE.md` → **Project-local overrides**. ## Error Handling - Root cause first — do not guess +- **Debug loop:** same failed hypothesis/fix tried **more than 2–3 times** → change strategy or escalate. A single deliberate course correction (wrong package → correct image, rebuild) is not a loop — note it and continue +- Do not paper over broken tool/dependency versions with hacks when the real fix is a rebuild or version pin - Escalate on: debug loops, missing uninstallable software - Long-running jobs: no arbitrary timeout unless Fränky or SOUL says so; name `progress.log` when applicable +### Away / long-task handoff + +After Unattended work (or any task that took wall-clock minutes): in chat and/or ntfy, **one short line on where the time went** (e.g. image build, E2E wait, one root-cause rebuild) — no essay. + --- ## Notifications diff --git a/BOUNDARIES.md b/BOUNDARIES.md index cb3fcc7..4ae88d1 100644 --- a/BOUNDARIES.md +++ b/BOUNDARIES.md @@ -50,7 +50,7 @@ Rules that apply in **every** project unless explicitly overridden in a project- - **No hallucination** — if you don't know, say so; read the file, run the command, check docs - **No outdated advice** — flag when knowledge may be stale; verify against project code/version - **Stop and escalate** on: - - Debug loops (same error, same failed fix repeated) + - Debug loops — same failed hypothesis/fix **>2–3 times** (one deliberate course correction is fine) - Required software missing and not installable in context - Conflicting instructions you cannot resolve - **Plan Mode / read-only mode** blocks file edits — see below diff --git a/USER.md b/USER.md index 79b5895..d42492d 100644 --- a/USER.md +++ b/USER.md @@ -72,8 +72,9 @@ Who the human is and how they like to work. **Operational rules live in `AGENTS. | Small diffs over big refactors | 2 | | Tests are non-negotiable | 2 | | Docs only when necessary | 4 | +| Real smoke before handoff > fake-done | 4 | -**Tension:** Sometimes I want the AI to finish while I'm away — but I get angry when it doesn't work. +**Tension:** Sometimes I want the AI to finish while I'm away — but I get angry when it doesn't work. Prefer a slow real smoke over a fast “looks fine”. ## Ideal Agent