| name | executing-large-tasks |
| description | This skill should be used when starting a large or multi-step task — a multi-file change or migration, a cross-module feature, a production incident, deep research or technology selection — or when work will span many tool calls, sessions, or packages, before code is written or an approach is committed to. |
Executing Large Tasks
Overview
Large tasks fail through process, not capability: plans built on unverified assumptions, big-bang changes, no rollback story, context loss mid-task, overclaimed results. The countermeasure is externalizing every judgment as a written, checkable artifact.
Core principle: a judgment that isn't written down with evidence didn't happen. Facts get source labels, plans get exit criteria, risks get verification actions, claims get observed output.
Incident override: when a production system is actively causing harm, production-safety.md §3 (contain → remediate → diagnose) preempts phases 1–3 below. Enter the Loop only after the bleeding is stopped.
The Loop
| Phase | Do | Exit criterion |
|---|
| 1. Scout | Measure reality before choosing an approach: count, sample, classify. Read the actual source of version-sensitive or internal interfaces you will rely on | Work inventory in numbers ("~320 sites: 210 pattern A / 80 B / 30 generated"); highest-leverage unknown identified |
| 2. Frame | Derive task-specific risks (deriving-perspectives.md). Label every load-bearing fact VERIFIED / INFERRED / ASSUMED (metacognition.md §1) | Prioritized checklist bound to phases; no ASSUMED or INFERRED interface fact left on the critical path |
| 3. Plan | Slice into independently verifiable increments. Design for failure: rollback, stop conditions, no-winner branch (production-safety.md) | Every slice has an observable exit check; failure branches written; the campaign ledger file is named, with its per-unit columns |
| 4. Execute | One slice at a time; ledger updated write-then-act (external-memory.md). Never stack a second unverified change on a first | Green gate per slice, recorded in the ledger |
| 5. Verify | Exercise the requested behavior end-to-end, not proxies. Run one refutation pass against your own conclusion (verification.md) | Every past-tense claim backed by output observed this session |
| 6. Report | Three buckets: VERIFIED / ASSUMED / NOT COVERED (verification.md §6) | Explicit verdict + evidence per acceptance criterion |
Non-negotiables
- Never build on an ASSUMED or INFERRED interface where it is version-sensitive, internal/undocumented, recently changed, or has two plausible behaviors (timeouts, retries, error shapes, nullability): read the source, run the discovery query, or check the installed version first. Ubiquitous stable APIs may stay INFERRED when a compile/typecheck/test tier would catch a mistake. Upgrading any label to VERIFIED requires citing the tool call in this session that verified it — a label without a citation is ASSUMED by definition.
- Enumerate all surfaces before design freeze. When changing a concept (money, auth, ids…), grep the concept repo-wide and list every touched surface: child tables (line items, taxes, payments), exports, mailers, webhooks, admin views, docs. The hardest correctness problems live in the child entities the task statement didn't mention.
- Every production-bound change names its off-switch and rollback path — including the data story — before rollout. Ship in monitored waves, not one end-of-project bake.
- Active harm → contain first, diagnose second. Freeze the trigger, remediate affected users, then root-cause.
- Write stop conditions in advance: the thresholds and discoveries that pause work and trigger consulting a human. Three failed attempts at one failure → apply the strategy-change rule in metacognition.md §6.
- Gate-based plans need a no-winner branch. Say now what happens if no candidate passes, the repro fails, or the assumption breaks.
- Every multi-unit campaign gets a persistent ledger — this means migrations (one row per call site or package), benchmarks and evaluations (one row per run/candidate, with configs), incident investigations (evidence log), and multi-day research (source and claim tracker). The plan names the ledger file and its columns before execution starts. Location: somewhere that survives session death and never enters the project diff — harness-designated persistent dir, else a gitignored repo path, else scratchpad. User and harness file rules take precedence; if creating files is forbidden, keep a structured state recap in your output and say that's the fallback.
- Expensive evaluations get a smoke run, a downselect ladder, and their own budget. Never full-scale everything on the first run.
- User urgency renegotiates scope, never evidence standards. Under time pressure, offer a smaller fully-verified slice or an explicitly flagged unverified delivery — never a silently unverified full delivery.
Reference files — load when the situation matches
| Situation | File |
|---|
| Starting: deriving the task-specific risk checklist | deriving-perspectives.md |
| Task will exceed ~10–15 tool calls; ledger format; subagent delegation; context budget | external-memory.md |
| Shipping to a running system; incidents; benchmarks/bake-offs | production-safety.md |
| Before claiming done/fixed/works; designing verification; reporting | verification.md |
| Debugging; confidence labeling; confusion vs. wrong; when to stop retrying | metacognition.md |
Common mistakes
- A detector blind to its own hypothesis (querying the local ledger for duplicates when the hypothesis is "crash before local commit") → validate the detector against each hypothesis before trusting its silence.
- Treating the ledger as a code-migration-only tool → benchmark campaigns, incident timelines, and research source-tracking need one just as much.
- Reciting this skill's checklists generically instead of instantiating them → every checklist item must name this task's file, table, metric, or command. A generic item is an unfinished item.
