# Lessons Learned

## Issue Management

**Put everything in the issue body.** Agents read the issue body; comments are unreliable. Add guidance by updating the body.

**One decision per issue.** Agents cannot choose between approaches. Decide before filing.

**Explicit dependencies prevent ordering bugs.** Use `Depends-on: #N` so agents don't work on stale code.

**Fit issues to templates.** Max 3 files, 5 acceptance criteria, clear solution. If it doesn't fit, it's too big—label `vision` and decompose.

## Debugging CI Failures

**Agents can't see CI logs.** When an issue fails repeatedly, diagnose externally and put the exact error and fix in the issue body.

**Blocked CI often means environment, not code.** Missing libraries, auth failures, or path assumptions usually point to infrastructure misconfiguration.

## Base Image and Environment

**Minimal images introduce hidden traps.** Alpine/musl libc breaks tools that work on glibc. Validate base image assumptions before committing to a path.

**Ask: "What system libraries does this tool actually need?"** Don't assume development environment constraints apply to production images.

**Document base image tradeoffs.** Alpine saves space but costs compatibility. Ubuntu saves compatibility but costs size. Make decisions explicit.

## Authentication

**Treat auth as first-class.** Authentication assumptions are the most fragile part of any integration.

**Audit all external calls.** Map every operation touching remote systems and verify each has proper auth—even internal repos can require credentials.

**Test in failure mode.** Don't just verify the happy path. Simulate restricted access environments.

**Verify the entire chain.** Each layer in a call chain can strip credentials. Check every script, command, and library boundary.

**Special cases often bypass standard flows.** "Edge" or "beta" builds frequently have auth gaps.

## Concurrency and Locking

**Scope conditions to the actor, not the system.** In multi-agent systems, distinguish "in progress" from "in progress by me."

**Design blocking points with "who does this affect?" comments.** Challenge any global-blocking condition: "What if five agents hit this simultaneously?"

**State falls into three categories:** global (affects all), actor-local, and shared resources. Only block on global state or own ownership.

## Branch and PR Hygiene

**Clean up stale branches before retrying.** Old branches cause recovery mode with stale code. Close PR, delete branch, then relabel.

**After a dependency lands, stale branches miss the fix.** If issue B depends on A and B's PR predates A's merge, close and recreate the branch.

## Feature Decomposition

**Prefer gluecode over greenfield.** Check existing APIs, libraries, or utilities before building new components.

**Max 7 sub-issues per sprint.** If more, split into two sprints.