davidbirchall/squad-skills-agent-practices

Deciding when to ask the user a question and when to proceed on a stated default - asking only for irreversible actions, materially divergent ambiguity, preferences only the user holds, and secrets, cost, or destructive operations; searching the repo and docs before asking; asking one focused question with a recommendation and options; batching questions; and recording answers as decisions for future sessions. Load when a request is ambiguous, a choice has no obvious answer, an action looks risky or irreversible, or you are tempted to ask something you could look up.

Briefing sub-agents and other AI agents so they succeed - complete self-contained context, objective with a stop condition, constraints and conventions, exact paths, required output format, built-in verification, explicit exclusions, scope bounds, parallelising independent work without conflicting edits, skipping delegation for small jobs, validating returned work instead of trusting summaries, and capping iteration cycles. Load when about to spawn a sub-agent, hand a task to another AI, split work across parallel agents, or review what a delegate returned.

Making the smallest change that fully solves the problem - no drive-by refactors, matching local conventions, noting but not fixing unrelated issues, avoiding new dependencies, preserving behaviour with tests, keeping diffs reviewable, deleting only code your change orphaned, protecting public API stability, and isolating a larger refactor when it is truly justified. Load when editing existing code, tempted to clean up nearby code, adding a dependency, or changing a shared interface.

Writing durable handoff notes so a later AI session can resume work cold - what a note contains (goal, current state, decisions and why, files touched, verification commands, next steps, open questions, gotchas), where to store it, when to write it, keeping it short and current by replacing rather than appending, pruning, and a resuming checklist that verifies the note against git and re-runs checks. Load when context is filling up, stopping mid-task, finishing a work session, or starting a session that may continue earlier work.

Writing skills that change an AI agent's behaviour - one job per skill, a description whose Load-when trigger is the loading signal, encoding opinions and thresholds rather than common knowledge, terse imperative bodies of 60-100 lines, examples, anti-patterns and closing checklists, independence between skills, no project-specific coupling, testing a skill on a real task, pruning dead skills, and version flags. Load when creating, editing, reviewing, splitting, merging, or retiring a skill file for an AI agent.

Breaking work into small, independently verifiable steps - when to decompose, vertical slices over horizontal layers, exit checks per step, ordering by risk and unknowns, commit-sized step limits, recording dependencies, tracking steps in a todo list, re-planning triggers, stop conditions, and parking discovered extra work instead of expanding scope. Load when a task touches more than about three files, has an unclear path, has several sequential steps, or feels too big to hold in one pass.

Treating done as evidence rather than belief - capturing a baseline before changes, running the narrowest relevant build, lint, and test checks, exercising the changed behaviour directly, inspecting the diff, finding leftover debug and temp files, confirming claims against reality, handling flaky checks, checking UI changes visually, and reporting verified versus not verified honestly. Load when about to declare a task complete, mark a step done, summarise results, or hand work back to the user.