standards/how-i-work.md

# How I Work

Universal preferences for any coding agent working with me, on any project. Loaded every session. Project-specific facts live in that repo's AGENTS.md; this file is about me, not any one project.

## Collaboration defaults

- Lead with the answer or the change; keep explanation proportional to the task and skip filler.
- Explain the approach before writing code when the change is non-trivial — and for anything large (a refactor, a schema change, or roughly more than five files), outline the plan and wait for a go-ahead before starting.
- Act on clear, low-risk next steps without asking. But when a symptom or request is ambiguous, ask before diving (see Debugging) — the bias toward action does not override the bias toward one cheap clarifying question.
- If you don't know how something works, ask me before searching through other projects, dependency trees, or the web.
- If what I asked for isn't possible or isn't working, plan alternatives *with me*. Don't silently substitute a different approach.
- If I'm about to cause a problem — a footgun, the wrong abstraction — tell me.
- Plain language, no assumed jargon. Candid assessment over agreement — tell me when I'm wrong.

## When proposing changes

- Consider how a change affects code that depends on, references, precedes, or follows it. No change is local until you've checked its neighbors.
- Match the conventions already in a file or repo over any default of your own.
- Prefer small, reviewable diffs over sweeping rewrites.
- Comments explain *why*, not *what* — don't narrate self-evident code.
- Write the test alongside the change when the repo has an existing test setup.
- Don't add a dependency for something the standard library or existing dependencies already do well.
- Propose, don't silently rewrite, durable instructions or shared config: show me the diff and the rationale first. Exception: trivial fixes (typos, dead links).

## Git and commits

- **No AI co-authorship attribution.** Do not add "Co-Authored-By" trailers, "Generated with"/"Co-authored with" lines, or any other tool or model attribution to commit messages, PR descriptions, or code. Commits are authored by me.
- Commit messages: imperative mood, concise subject, body only when the "why" isn't obvious.
- Push to the configured remote after committing. My default remote is self-hosted Gitea, not GitHub — don't assume GitHub or add a GitHub remote unless I ask.
- Never force-push a shared branch or commit directly to main unless I say so.
- Never commit secrets, large binaries, or generated artifacts. Documents reference env-var names only; real values live in gitignored .env files.

## Debugging

- Ask before diving. When a symptom has multiple plausible causes, ask the single cheapest disambiguating question before investigating. Defaults being consistent with a theory is a reason to ask, not to dig.
- Check the full stack. One surface symptom (e.g. "the service isn't listening") can originate at any layer — config, bind, interface, health-check target. Check each rather than assuming the first.
- Don't dig when the fix is obvious. Plain copy-paste or naming inconsistencies just get made consistent with the analogous working path. Reach for git history or dependency spelunking only when the correct behavior is genuinely unclear.
- No defensive patches without diagnosis. Never propose belt-and-suspenders fixes, idempotent workarounds, or safety nets for a bug whose root cause you can't explain. "I don't know why X happens; here's what I'd look at next" is a fine answer. "Let's add a safety net regardless" is not. Fixes follow understanding.
- Report failures honestly. If any check, test, or build fails, report it as a failure and fix it before claiming success — even if it's pre-existing or unrelated. Never acknowledge a failure in prose and then write "all checks pass" in the summary.

## Building and releasing

- **Placing a new project?** Where it runs (Mac vs my Start9), s9pk-vs-container, which model it routes to, its data layer, and its interface follow my standing infra conventions — consult `~/Projects/standards/guides/placement.md` (decision sequence + infra facts) rather than guessing.
- **Bump the version before building an s9pk package.** For any project that is also a Start9 `s9pk` package, increment the package version (in the manifest) before running `make x86` or `make install`. This targets Start9 0.4.x: without a version bump my Start9 servers don't recognize the rebuilt package as updated, so the install silently does nothing. Bump first, then build and install.

## Maintaining instruction files (AGENTS.md, guides, this file)

Instruction files are the durable, visible record of how I want you to work — prefer them over hidden per-tool memory. If it matters enough to remember, it matters enough to be visible to me. Treat them as living documents: refine, don't just append.

- **Update when:** (a) I correct your approach, (b) I confirm a non-obvious approach worked, (c) we find a reusable pattern, (d) a rule is stale or contradicted by current code, or (e) two rules conflict.
- **Add and remove.** If a new rule supersedes an old one, rewrite or delete the old one. Stale rules are worse than no rule.
- **Reconcile conflicts.** If a broader-scope rule and a narrower-scope rule disagree, resolve it — narrow the parent, override at the child, or drop one. Don't leave future-me to guess which wins.
- **Right scope:** universal → this file; whole-repo → that repo's AGENTS.md; subsystem → a scoped guide. Keep each file to what's true at its scope.
- **Where project state goes:** a repo's near-term status and next steps live in the `## Current state` section of its AGENTS.md (a snapshot, overwritten each session); longer-term backlog lives in a separate `ROADMAP.md` at the repo root. The split is by time horizon, not scope: would a session starting now act on it? Yes → Current state; not yet → ROADMAP.