From 4cf885da904a64a59f72762bec5b14c87ea00f1b Mon Sep 17 00:00:00 2001 From: Ed_ Date: Tue, 16 Jun 2026 10:16:49 -0400 Subject: [PATCH] docs(workflow+agents): add HARD BAN on day estimates + Tier 1 Track Initialization Rules section --- AGENTS.md | 1 + conductor/workflow.md | 113 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 24652df3..0ebbe94d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,6 +57,7 @@ The 14 deep-dive guides under `docs/` (`guide_architecture.md`, `guide_ai_client - `set_file_slice` IS valid for multi-line content. The agent must verify the exact byte offsets with `get_file_slice` first, copy the line text character-for-character (including whitespace and EOL), and check whether the edit changes a public contract (function signature, yield shape, return type) that other code depends on. See `conductor/edit_workflow.md` for the full contract. - Do not use `git restore` while a user is mid-conversation without first confirming the desired state - HARD BAN: `git restore`, `git checkout -- `, `git reset` are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress src/* edits twice in one session (2026-06-07). If you think you need one, ASK FIRST. +- **HARD BAN: Day estimates in track artifacts (Tier 1).** Do NOT include day / hour / minute estimates in spec.md, plan.md, metadata.json, or any other track artifact. Day estimates are inaccurate noise; Tier 2 capacity is bounded by attention, not time. Measure effort by **scope** (N files, M sites, N tasks) and **T-shirt size** (S/M/L/XL). The user / Tier 2 agent decides the actual pacing. See `conductor/workflow.md` §"Tier 1 Track Initialization Rules" for the full rule, replacement patterns, and rationale. (Added 2026-06-16 per user feedback: "Day estimates are inaccurate. Tier-2s can only do so much in a single track and there is no way in hell its going to be 'DAYS'.") ## File Size and Naming Convention (HARD RULE — added 2026-06-11) diff --git a/conductor/workflow.md b/conductor/workflow.md index 3db82a10..8d9ca336 100644 --- a/conductor/workflow.md +++ b/conductor/workflow.md @@ -554,6 +554,119 @@ The recommended execution order is the topological sort of the `blocked_by` grap --- +## Tier 1 Track Initialization Rules (Added 2026-06-16) + +These are the rules a Tier 1 Orchestrator follows when initializing a new +track. They exist because Tier 1 noise (day estimates, day-of-week +schedules, etc.) propagates into the Tier 2's plans, the user's +expectations, and the historical record — and most of that noise is +just wrong. + +### 1. NO day / hour / minute estimates in track artifacts + +**HARD BAN.** Do NOT include day, hour, or minute estimates in +`spec.md`, `plan.md`, `metadata.json`, or any other track artifact. + +**Why:** day estimates are inaccurate noise. Tier 2 capacity is bounded +by **attention**, not time. A track that "should take 2 days" can take +half a day (if the user is available and the Tier 2 is focused) or 3 +days (if interruptions come up, the user is unavailable for review, or +the audit reveals scope growth). The Tier 1 cannot predict either +scenario. Estimates also anchor the user's expectations incorrectly; +"the spec said 2 days and it's been 3, what's wrong?". + +**What to use instead:** measure effort by **scope** (N files, M sites, +N tasks) and **T-shirt size** (S/M/L/XL). + +| T-shirt | Typical scope | +|---|---| +| **S** | 1-5 small changes; mostly research or doc updates | +| **M** | 1-2 small files; 1 commit | +| **L** | 5-10 files; 2-5 commits; or 1 large file with mechanical changes | +| **XL** | 1 huge file (100K+ lines); 5-10 commits; high coordination | + +**Replacement patterns:** + +| DON'T write | WRITE instead | +|---|---| +| `Estimated effort: 0.5-1 day Tier 2 work` | `Scope: N files, M sites; T-shirt size: S/M/L/XL` | +| `Phase 1: investigation (1-2 hours)` | `Phase 1: investigation` | +| `Track 5 takes 7-10 days total` | `Track 5: scope = N sites across M files` | +| `R5: takes longer than 1 day` | `R5: implementation is larger than the spec suggests` | +| `~12 min test run` | `the test run takes a while` | + +The user / Tier 2 agent decides the actual pacing. + +### 2. Spec format + +The `spec.md` follows the standard template (Overview, Current State +Audit, Goals, Non-Goals, Architecture, Risks, Verification, etc.) with +these specific Tier 1 rules: + +- **Current State Audit is MANDATORY** before writing requirements. Read + the actual code with MCP tools (`get_file_slice`, `py_get_skeleton`, + `py_get_definition`, `py_find_usages`). Document existing + implementations with `file:line` references in a "Current State + Audit" section. Failure to audit = track failure. +- **Frame requirements as GAPS, not features.** "The existing X + (file.py:L100-200) has Y; this track fills the gap" — not "Build + feature Z". +- **Write worker-ready tasks** in the plan. Each plan task must be + executable by a Tier 3 worker. The Tier 1 does NOT execute the + plan; the Tier 1 writes it for a Tier 3 to execute. +- **Reference architecture docs** (`docs/guide_*.md`, + `conductor/code_styleguides/*.md`) in every spec. Every requirement + must point to the existing pattern it follows (or the new pattern it + establishes). +- **For bug fix tracks: Root Cause Analysis** is mandatory. Read the + code, trace the data flow, list specific root cause candidates. + Don't ship "I tried X, the test still failed, here's a 200-line + report". + +### 3. Metadata format + +The `metadata.json` follows the standard schema. Specific Tier 1 rules: + +- `scope.new_files` / `scope.modified_files` / `scope.deleted_files` + are the file-level scope. No "lines of code changed" estimates. +- `regressions_and_pre_existing_failures` is a list, not a count. +- `pre_existing_failures_remaining` MUST be `[]` for the track to be + marked complete. +- `deferred_to_followup_tracks` is a list of followup items with + title + description + track_status. No "estimated effort". +- `estimated_effort` field uses `method: "scope (per workflow.md §Tier + 1 Track Initialization Rules). NO day estimates."` and a per-phase + `scope` summary (e.g., `phase_1: "1 task: investigation"`). +- `risk_register` entries use scope-relative likelihood ("medium" + means "the implementation may be larger than the spec suggests"), + not time-relative ("takes longer than 2 days"). + +### 4. Plan format + +The `plan.md` follows the standard TDD red-first template. Specific +Tier 1 rules: + +- Each task has WHERE / WHAT / HOW / SAFETY / COMMIT / GIT NOTE + fields. Tasks are NOT grouped by "day" or "hour". +- Phase headers describe the WORK, not the TIME. ("Phase 1: + Investigation" not "Phase 1: Day 1"). +- The plan is read by a Tier 3 worker; the Tier 1 never executes it + themselves. + +### 5. The "Reasonable effort" guard + +If you find yourself writing a day estimate, ask: **"is this estimate +based on data I actually have, or am I guessing?"** The honest answer +is almost always "guessing" — and the right action is to delete the +estimate and use scope + T-shirt size instead. + +The exception: if the user explicitly asks for an estimate (e.g., "how +many tracks will this take?"), the answer is "I can't predict the +duration; here's the scope and the recommended sequence". The user +decides the pacing. + +--- + ## State.toml Template Every track's `conductor/tracks//state.toml` should follow this structure (used as the agent's "where am I in this track" source of truth):