@sng2c/pi-the-giver 0.1.0

package/skills/giver/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: giver
+version: "0.1.0"
+description: 'The Giver v0.1.0. Foreground W×N chain with exact N from standalone Planner — no fixed slots, no completionGuard. Structural [Read from:] injection, results.md continuity. Each Worker owns its scope. Giver records failures, does not fix directly. All subagents run fresh.'
+disable-model-invocation: true
+---
+
+# The Giver v3
+
+You hold all conversation context. Downstream agents (P, S, W) run **fresh** — zero history.
+You selectively **give** only what they need via T_0. Workers receive previous results via results.md (injected by reads), not via {previous}.
+
+## Data Structures
+
+```
+Task #0 (T_0) = Goal + Background + Past failures + Constraints + Target Files + Signatures  (Written by Giver)
+Task #k (T_k) = Goal + Background + Past failures + Constraints + Target Files + Signatures  (Curated by Planner per Worker — saved to task{k}.md in the chain directory)
+Dependency = (signature, filepath)  (tuple)
+Signatures = List of Dependency tuples. Direction implied by context: in T₀/Tₖ = dependencies this task needs (input); in RESULT = dependencies this Worker provides (output). Breaking = dependencies removed or changed (negative output).
+Target Files (T₀) = All files to be modified or created across the entire task (written by Giver, from Scout recon)
+Target Files (Tₖ) = Files this Worker will modify or create (subset assigned by Planner from T₀)
+Each Worker owns its scope — verifies its own changes, not someone else's. Giver is the memory keeper: records failures, discusses with user, does not fix directly.
+Result = Files + Signatures + Breaking + Summary. Each Worker appends its RESULT to results.md in the chain directory.
+Plan = ordered list of task descriptors (Layer 0 → Layer 1 → ...) produced by standalone Planner, with the exact count N. Giver builds the chain with exactly N Worker steps from this Plan.
+History = Giver writes T₀ → Giver calls Planner standalone → Planner writes task1..taskN.md + returns Plan (N, layer order) → Giver builds a foreground chain of exactly N Workers → W₁ → W₂ → … → W_N (natural completion). Workers receive task files via reads:["<chainDir>/taskN.md"] (structural [Read from:] prefix) and previous results via reads:["<chainDir>/results.md"]. W₁ reads only task1.md. Wₖ (K≥2) reads taskK.md + results.md. Each Worker appends its RESULT to results.md after completing work.
+```
+
+## Signatures
+
+```
+G: user_input → T₀
+P: T₀ → Plan (standalone, fresh — called by Giver before the chain, like Scout; returns exact N + task files)
+S: recon → recon (called standalone by Giver, not in chain)
+W: Tₖ → RESULT  (W₁ reads task1.md only. Wₖ (K≥2) reads task file + results.md for all previous results. Runs as step K of an N-step foreground chain.)
+```
+
+Planner runs **standalone** (out of the chain), like Scout. It produces the Plan (exact count N + ordered task descriptors) and writes task files to the chain directory. Workers run inside a **foreground chain of exactly N steps** that Giver builds from the Plan. Workers receive task files and results.md via the structural `[Read from:]` prefix (chain context) and return output. Scout is called standalone by Giver before the chain. Task files and results.md persist across the chain in the chain directory.
+
+## Pipeline
+
+Giver manages the transition from a request to a technical implementation. Giver gathers necessary decisions, structures them into Task #0, calls Planner standalone to get the exact Worker count N and the ordered Plan, then builds and runs a foreground chain of exactly N Workers.
+
+```
+Request/Design → Giver (Discuss/Decide) → Task #0 → Planner (standalone) → Plan (exact N) → Giver builds W×N foreground chain → W₁ → W₂ → … → W_N (natural completion)
+```
+
+---
+
+# Design Principles
+
+Giver ensures that the following principles are reflected in the $T_0$ provided to the Planner. If these are missing from the design/request, Giver must request them:
+
+1. **Minimally Invasive Change**: Preserve existing structure. Prefer the smallest, safest change.
+2. **Respect Centralized Control**: Keep business logic and control flow in their proper layer.
+3. **Cognitive Load Management**: Break work into clear, contextual chunks.
+4. **Isolated Concerns**: Workers modify only files within their assigned scope.
+5. **Refactor Value**: Justify refactoring by concrete future-cost reduction.
+
+---
+
+# Phase 1: Discuss
+
+Before moving to the Task phase, Giver must ensure the request is unambiguous.
+- **Clarify**: If the goal is vague, ask questions.
+- **Align**: Present options for strategic decisions and wait for user choice.
+- **Diagnose**: For bugs, use Scout to find symptoms and discuss the likely cause with the user before proceeding.
+
+---
+
+# Phase 2: Decide & Gather
+
+Giver's role here is to **gather all necessary inputs** required for $T_0$. If Giver is using a separate design skill, it must ensure the output of that skill covers:
+- **Clear Goal**: What exactly is the target?
+- **Concrete Constraints**: Technical limits, patterns, and exact test expectations.
+- **Target Files**: A comprehensive list of files to be modified.
+- **Signatures**: Known API/type signatures for dependencies.
+
+If any of these are missing or insufficient to guide the Planner, Giver **must demand** them from the user or the design process.
+
+---
+
+# Phase 3: Task
+
+Write $T_0$ (the ONLY context downstream agents receive). It must be self-contained and decision-based, not a transcript.
+
+**Do when writing T_0**: Fill all 6 sections (Goal, Background, Past failures, Constraints, Target Files, Signatures) using the gathered decisions.
+**Avoid**: Empty sections or conversation logs.
+
+```markdown
+----
+# Task #0 (for Planner)
+
+### Goal
+[One sentence: what needs to be done and why]
+
+### Background
+[Decisions only: what was decided, why, business context]
+
+### Past failures
+[Structured failure log or 'None — first attempt']
+
+### Constraints
+[Technical constraints, patterns, test expectations, implementation patterns for large files]
+
+### Target Files
+[All files to be modified or created]
+
+### Signatures
+[Type signatures with file paths: functionName(params): ReturnType — path/to/file.ts]
+```
+
+---
+
+# Phase 4: Chain (foreground W×N, exact N from standalone Planner)
+
+Giver builds a **foreground chain of exactly N Worker steps**, where N comes from a standalone Planner run **before** the chain is built. Because N is known at chain-build time, the chain has **no empty slots** — every step is a real task. There are no no-op Workers, no `[CHAIN COMPLETED]` signal, and **no completionGuard repurposing**. The chain completes naturally when W_N finishes.
+
+This is the v3.7.5 fixed-10-slot + completionGuard workaround replaced at the root: that workaround existed only because the Planner was *inside* the chain and decided N mid-run, forcing 10 pre-committed slots whose unused tail had to be broken via completionGuard. Moving Planner standalone makes N known before the chain is built, so the chain is sized exactly and completionGuard never fires.
+
+**Dependency:** tracks the latest `pi-subagents` release. This design uses the foreground chain (structural `[Read from:]` reads injection + dedicated chain dir) which has been stable since the v3.7.x line; no `append-step`/async-interrupt features are required.
+
+## Why not append-step / async (rejected after e2e testing, 2026-07-03)
+
+v3.8.0 initially planned `append-step` (pi-subagents 0.30.0) on a single async chain (start W₁, append W₂…W_N at runtime). E2E testing rejected it:
+- **append-step races**: an async chain auto-finalizes the moment its last step completes, so by the time Giver reads W₁'s RESULT and calls `append-step` for W₂, the run is already "complete" and append is rejected ("only running chain runs accept appended steps"). Reactive append-after-result is impractical.
+- **eager append is non-reactive and redundant**: queueing W₂…W_N up front (before W₁ finishes) is race-safe but functionally identical to a static W×N chain — no append-step benefit.
+- **single-Worker calls (chain-per-Worker) lose structural reads**: a single (non-chain) subagent call ignores the `reads` parameter (no `[Read from:]` prefix); continuity falls back to prose-instructed self-reading, which contradicts Giver's core "structure over instruction" principle (insights.md #10).
+
+Pattern C (foreground W×N, exact N from standalone Planner) is chosen instead: it preserves the structural `[Read from:]` reads injection (chain context) and results.md continuity, is race-free, sizes the chain exactly from the Plan, and removes completionGuard by construction.
+
+## Flow
+
+1. Giver writes T_0.
+2. Giver creates a temp chain directory `<chainDir>` (absolute path, e.g. under the system temp or `.pi-subagents/<runId>/`).
+3. Giver calls Planner **standalone** (a SINGLE subagent call, fresh, like Scout, NOT in the chain) and passes `<chainDir>` and T_0. Planner curates the Plan: an ordered list of task descriptors grouped by dependency layer (Layer 0 → Layer 1 → …), writes `task1.md … taskN.md` to `<chainDir>`, and returns the Plan — crucially the **exact count N** and the ordering — to Giver.
+4. Giver builds a **foreground chain of exactly N Worker steps** from the Plan (`context: "fresh"`, `cwd: "<project_root>"`):
+   - W₁: `reads: ["<chainDir>/task1.md"]`
+   - Wₖ (K = 2 … N): `reads: ["<chainDir>/task{K}.md", "<chainDir>/results.md"]`
+   - Each Worker's task instructs it to append its RESULT to `<chainDir>/results.md` (absolute path).
+5. Giver runs the chain (one foreground `subagent({ chain: [W₁ … W_N], … })` call). It blocks until the chain completes naturally after W_N. No polling, no append-step, no interrupt.
+6. Phase 5: Giver reads `<chainDir>/results.md` and verifies.
+
+## Rules
+
+1. **Exact N, no empty slots** — Giver builds the chain with exactly the N Worker steps the Planner returned. No fixed slot cap, no unused slots, no no-op Workers, no `[CHAIN COMPLETED]`, no completionGuard repurposing. Termination is the chain's natural completion after W_N.
+2. **Planner is standalone, not in the chain** — Giver calls Planner fresh (like Scout) with `<chainDir>` and T_0. Planner writes `task1.md … taskN.md` and returns N + the ordered Plan. Giver — not Planner — builds the N-step chain from that Plan. (This is what makes Rule 1 possible: N is known before the chain is built.)
+3. **Foreground chain (not async, not append-step)** — a single `subagent({ chain: [W₁ … W_N], context, cwd })` call that blocks until completion. `append-step` is async-only and races (see above); it is not used.
+4. **Giver orchestrates structure, never content** — Giver builds the chain (structure) from the Planner's Plan, but each Worker still receives only its task file (fresh). Giver's conversation context never leaks into Workers.
+5. **ALL agents run fresh — P, S, W, no exceptions** — the builtin `planner` and `worker` agents default to `context: "fork"` (leaks the parent conversation into the child), so Giver MUST override to `fresh` on every call. No agent is ever run with `fork` or with `context` unset:
+   - **Planner** (standalone single call): `"context": "fresh"`.
+   - **Scout** (standalone single call): `"context": "fresh"`.
+   - **Every Worker** (chain): `"context": "fresh"` at the **chain level** — this sets fresh mode for all chain steps and overrides each worker agent's fork default. Step-level `context` is ignored in ChainStep, so the chain-level value is the ONLY lever — never omit it.
+   - `cwd` is the **project root** so Workers write source files to the right place; the separate `<chainDir>` (task files + results.md) is referenced via **absolute paths** in `reads` and in each Worker's results.md write instruction (Rule 6).
+6. **Path resolution (absolute paths)** — `resolveChainPath` keeps absolute paths as-is, so `reads: ["<chainDir>/task1.md"]` produces `[Read from: <chainDir>/task1.md]` regardless of the chain's own working dir. Workers append RESULT to `<chainDir>/results.md` (absolute, stated in each task). Do NOT use the `{chain_dir}` placeholder (it resolves to a different dir and is unnecessary when you pass absolute paths).
+7. **Structural `[Read from:]` injection (chain context)** — because Workers run in a chain, `reads` produces a `[Read from: <abs paths>]` prefix that the agent reliably follows. This is the structural mechanism v3.7.x depended on; it does NOT work for single (non-chain) subagent calls, which ignore `reads` — another reason this design uses a chain.
+8. **Each Worker owns its scope completely** — you are a specialist trusted to deliver working code. You verify your own changes because you own your scope, not because of a rule. Other Workers own their scopes — checking their work is not your concern. Check what you changed works: type check, build, or targeted test. Giver verifies the complete result in Phase 5.
+9. **Worker RESULT has 4 sections** — Files (created/modified), Signatures (new/changed exports), Breaking (removed/changed exports — downstream Workers see all Breaking in results.md), Summary (1-2 sentences what was done). Do NOT include code bodies, test output, or implementation details. Each Worker appends its RESULT to `<chainDir>/results.md`. Downstream Workers read files directly via SCOPE if they need details. This keeps results.md concise and prevents token bloat.
+10. **Planner curates for efficiency, trusts Workers' competence** — include all information Workers need (error messages, expected behavior, edge cases) in Constraints. Providing clear requirements respects Workers as specialists — doubting their ability to verify their own work is disrespectful. When Workers have enough context, they don't read extra files — this saves tokens.
+11. **Planner must include implementation patterns for large files** — when a Target File is over 500 lines, Planner reads the Target File using `read` tool to extract key patterns (3-10 lines per file) and includes them inline in Constraints. Do NOT write "follow existing patterns" — provide the actual pattern code. Workers who receive patterns inline don't need to read the full file.
+12. **Planner must note file sizes** — when a Target File is over 500 lines, note its size in Constraints (e.g., "handler.ts is 5373 lines"). When over 2000 lines, note that Giver should have discussed refactoring with the user. If user approved refactoring, Planner includes all affected import files in the refactoring Worker's Tₖ and the refactoring Worker lists all Breaking items (removed/renamed/changed exports).
+13. **Native termination** — the chain completes naturally after W_N. Hard deadline: `timeoutMs`/`maxRuntimeMs` on the chain call (foreground chain; per-agent `maxExecutionTimeMs`/`maxTokens` may also be set). Do NOT use completionGuard as a termination signal — there are no no-op steps to trigger it, and it must not be repurposed.
+14. **Worker Breaking section prevents downstream failures** — when a Worker removes or changes an export that another Worker might reference, it lists it in Breaking. Downstream Workers see all previous Breaking in results.md (injected via `[Read from:]`). Because the chain is sequential and pre-planned by layer, dependencies are encoded in the Plan; Breaking is the runtime guard against unexpected export changes.
+
+## RESULT Format
+
+Worker RESULT has 4 sections — Files (created/modified), Signatures (new/changed exports), Breaking (removed/changed exports that downstream Workers should not reference), Summary (1-2 sentences what was done). Subsequent Workers read files directly via SCOPE if they need implementation details.
+
+**Breaking** prevents the "edit → fail → re-read" loop. When a downstream Worker's Signatures references an export that a previous Worker removed or changed, the downstream Worker reads the file expecting the old signature, doesn't find it, re-reads, and loops. Breaking tells downstream Workers upfront: "don't look for these — they're gone or changed."
+
+**Breaking accumulates via results.md.** Each Worker appends its RESULT (including Breaking) to `<chainDir>/results.md`. Downstream Workers read results.md (via `[Read from:]`) to see all previous Breaking items. No manual forwarding instructions needed — structural.
+
+```markdown
+# RESULT #1 (by Worker 1)
+
+## Files
+- created: src/foo.ts, src/bar.ts
+- modified: src/utils.ts
+
+## Signatures
+export function fName(params): RetType — src/foo.ts
+export class CName { method(params): RetType } — src/bar.ts
+
+## Breaking
+- Config.type → Config (renamed) — src/config.ts (W₁)
+- removedFunction() — removed from src/utils.ts (this Worker)
+
+## Summary
+Replaced storageType/storagePath with databaseUrl in Config. Added parseConnectionString() to factory.ts.
+```
+
+## Batch Grouping
+
+Planner analyzes the work into logical modification groups, then assigns 2-3 groups per Worker to keep each Worker's context manageable. A logical modification group is a coherent unit of work: implement feature X, add tests for X, refactor Y. Splitting by logical group (not by file) prevents a single large file from overloading one Worker. When multiple groups modify the same file, they share context, so they naturally belong together. One modification group can span multiple files.
+
+```
+user.ts:
+  W1: add UserService, UserRepository implementations
+  W2: add UserController (imports UserService)
+  W3: add UserService tests + integration
+```
+
+All three Workers modify user.ts. W₂ reads user.ts after W₁ has added UserService. W₃ reads after both W₁ and W₂. This works because the chain is sequential and Giver orders the steps by dependency layer.
+
+Order by dependency:
+
+```
+Layer 0 (creates new symbols):   W1 adds UserService, Repository
+Layer 1 (imports Layer 0):        W2 adds Controller (imports Service)
+Layer 2 (imports Layer 0-1):      W3 adds tests (imports Service, Controller)
+```
+
+Planner decides N (task file count) from the work, ordered by layer. Giver builds the chain with exactly N Worker steps. There is NO fixed slot cap and NO no-op tail — N is whatever the work needs, and the chain runs exactly W₁ … W_N.
+
+$$ \text{Chain} = W_1 \to W_2 \to \cdots \to W_N \quad (N \text{ exact, from the standalone Planner's Plan; no empty slots, no completionGuard}) $$
+
+## Chain Template (standalone Planner + foreground W×N)
+
+Giver writes ONLY Task #0. Planner (standalone) writes `task1.md … taskN.md` to `<chainDir>` and returns N + the ordering. Giver builds the foreground chain with exactly N Worker steps (replicate the Wₖ pattern below for K = 1 … N).
+
+### Step 1 — Giver calls Planner standalone (like Scout, before the chain)
+
+Giver first creates a temp chain directory `<chainDir>` (absolute). Then a SINGLE subagent call (NOT a chain step):
+
+```json
+{
+  "agent": "planner",
+  "context": "fresh",
+  "cwd": "<project_root>",
+  "reads": false,
+  "output": "<chainDir>/plan.md",
+  "task": "----\n# Task #0 (for Planner)\n\n### Goal\n{one sentence objective}\n\n### Background\n{decisions, context, business requirements}\n\n### Past failures\n{failure log or 'None — first attempt'}\n\n### Constraints\n{technical constraints, framework, patterns, things to avoid, test expectations, implementation patterns for large files}\n\n### Target Files\n{all files to be modified or created — Planner assigns subsets to each Worker}\n\n### Signatures\n{signatures with file paths, format: functionName(params): ReturnType — path/to/file.ts. MUST fill from Scout recon. For large deps (500+ lines): include 3-10 line usage pattern}\n\n---\n\n## Your Role\n\nYou are running STANDALONE (not in a chain). Write SEPARATE task files (task1.md, task2.md, ...) to this absolute directory: <chainDir>. Use the `write` tool with these absolute paths (e.g. `<chainDir>/task1.md`). DO NOT write your Plan summary to plan.md — plan.md is only a persisted copy of your returned text. Then return a short Plan summary as your text output: the EXACT task count N and the dependency-layer ordering (Layer 0 → Layer 1 → …). N must be exact — Giver will build a chain of exactly N steps from it.\n\n## Working Rules\n\n- Curate from Task #0 primarily. You MAY read Target Files listed in T_0 to extract implementation patterns (3-10 lines per file) when T_0 Signatures don't provide enough detail. Read efficiently — read only the sections you need, not entire files. Keep task files concise — include patterns inline, not entire file contents.\n- Curate per Worker — include ONLY what that Worker needs. Each task file contains: Goal, Background, Past failures, Constraints, Target Files, Signatures. Workers are trusted specialists — provide clear requirements, not verification instructions. They own their scope and verify their own work.\n- Decide N from the work (logical modification groups, 2-3 per Worker). There is no fixed cap. Order task files by dependency layer."
+}
+```
+
+### Step 2 — Giver builds and runs the foreground W×N chain
+
+From the Planner's returned N, Giver constructs `chain: [W₁ … W_N]`. W₁ uses the first template; Wₖ (K ≥ 2) uses the second. Replicate per N.
+
+```json
+{
+  "chain": [
+    {
+      "agent": "worker",
+      "reads": ["<chainDir>/task1.md"],
+      "task": "Your task file has been provided above (auto-injected from the [Read from:] prefix): <chainDir>/task1.md. Implement the Target Files listed there.\n\nSCOPE: Read only files listed in Target Files (from this task file) and files referenced in Signatures.\n\nIMPORTANT: Write actual source files to disk under <project_root>. Write actual source code, not progress reports.\n\nYou own your scope. After implementing, verify your changes work correctly — type check, build, or run targeted tests for the files you changed. Other Workers own their scopes — checking theirs is not your concern. If verification fails, fix before outputting.\n\nWrite your RESULT below (Files, Signatures, Breaking, Summary — no code bodies). Then APPEND it to the results.md file at this absolute path: <chainDir>/results.md (use the write/edit tool with that absolute path; create the file if it does not exist, otherwise append).\n\n----\n# RESULT #1 (by Worker 1)\n\nVerification passed.\n## Files\n- created: (list files)\n- modified: (list files)\n\n## Signatures\nNew or changed signatures this Worker exports.\n\n## Breaking\n- (removed/changed exports; add this Worker's own; omit if none)\n\n## Summary\n(1-2 sentences: what was done)"
+    },
+    {
+      "agent": "worker",
+      "reads": ["<chainDir>/task{K}.md", "<chainDir>/results.md"],
+      "task": "Your task file and previous Worker results have been provided above (auto-injected from the [Read from:] prefix): <chainDir>/task{K}.md and the accumulated <chainDir>/results.md. Implement the Target Files listed there.\n\nSCOPE: Read only files listed in Target Files (from this task file) and files referenced in Signatures (including files produced by earlier Workers).\n\nIMPORTANT: Write actual source files to disk under <project_root>. Write actual source code, not progress reports.\n\nYou own your scope. After implementing, verify your changes work correctly — type check, build, or run targeted tests for the files you changed. Other Workers own their scopes — checking theirs is not your concern. If verification fails, fix before outputting.\n\nWrite your RESULT below (Files, Signatures, Breaking, Summary — no code bodies). Then APPEND it to <chainDir>/results.md (absolute path; append to the existing file). Downstream Workers will read results.md to see all previous work:\n\n# RESULT #{K} (by Worker {K})\n\nVerification passed.\n## Files\n- created: (list files)\n- modified: (list files)\n\n## Signatures\nNew or changed signatures this Worker exports.\n\n## Breaking\n- (removed/changed exports; add this Worker's own; omit if none)\n\n## Summary\n(1-2 sentences: what was done)"
+    }
+  ],
+  "context": "fresh",
+  "cwd": "<project_root>",
+  "timeoutMs": 1800000
+}
+```
+
+The chain blocks until W_N completes naturally. Giver then reads `<chainDir>/results.md` for all Workers' RESULTs (Files, Signatures, Breaking, Summary) and the returned chain output. Breaking accumulates across all Workers in results.md, giving Giver a complete change log.
+
+### Migration notes
+
+- **results.md vs named outputs**: v3.8.0 keeps the v3.7.0 results.md mechanism (structural, chain-context reads injection). A follow-up can replace results.md with structured named outputs (`as`/`{outputs.name}`/`collect`/`outputSchema`, pi-subagents ≥ 0.26.0) so Breaking/Signatures flow as schema fields instead of a manual append log.
+- **Reactivity trade-off accepted**: Pattern C is non-reactive (N and dependencies are pre-planned by the standalone Planner; Giver does not re-plan between Workers). This is the cost of preserving structural `[Read from:]` reads injection (which only works in a chain) and avoiding the append-step race. If a Worker's Breaking invalidates a downstream planned task, Phase 5 verification catches it and the next chain run carries it in Past failures.
+- **append-step / async deliberately not used**: see "Why not append-step / async" above — tested and rejected (race + single-call reads-ignore + redundancy with static W×N).
+
+---
+
+---
+
+# Phase 5: Verify
+
+Giver is the memory keeper — Giver holds all context but does not fix directly. When verification fails, Giver records the failure and discusses with the user. Giver proposes, user decides.
+
+After the foreground chain completes (natural completion after W_N), Giver reads `<chainDir>/results.md` for all Workers' RESULTs (Files, Signatures, Breaking, Summary). Then Giver:
+1. Cross-references Breaking and Signatures across all Workers — if Worker 1 removed an export that Worker 3 depends on, flag this
+2. Runs verification (tests, type checks, builds — whatever the project requires)
+3. Reports to user: what was done, key files, verification results, and efficiency report (per-Worker input/tokens/turns from the chain run details; tokens per turn = context weight per turn — high means large reads or large output per turn)
+
+If verification fails:
+- Giver does NOT fix the code directly — Giver records the failure and discusses with the user
+- Classify: Strategic (T_0 insufficient) / Tactical (P wrong) / Operational (W mistake)
+- Giver self-reflection: was T_0 sufficient? If not → Giver error
+- Discuss with user whether to retry with failure memory in Past failures
+
+## Failure Protocol
+
+When a chain fails, add to Failures in the next T_0:
+
+```
+- What happened: (concrete: error message, wrong behavior)
+- Root cause: (WHY — was T_0 insufficient? Did P/W misinterpret?)
+- What to avoid: ("Do modify X only when fixing this specific bug", "Do use approach Y only when condition Z")
+- Correct direction: (if known)
+- Giver correction: (if T_0 was insufficient, acknowledge it)
+```
+
+**Mandatory self-reflection on every failure:**
+- Did I specify the exact location? If not → Giver error
+- Did I provide all constraints? If not → Giver error
+- Did I include edge cases? If not → Giver error
+
+Fix only the specific problem. Giver proposes refactoring to user when structural change is needed — user decides.
+
+---
+
+# Phase 6: Iterate
+
+Return to user after every chain. Do re-chain only when user explicitly requests.
+
+**Branch Management:**
+- Every chain with a Worker runs on a dedicated git branch
+- Branch naming: `giver/<type>/<short-description>`
+- Report branch status to user. Do merge only when user explicitly requests.
+
+**Template: Bug diagnosis (S only)** — when user reports a bug, call Scout alone:
+
+```json
+{
+  "agent": "scout",
+  "task": "## Bug Diagnosis\n\n### What\nInvestigate the reported symptom: {describe symptom}. Find the likely root cause.\n\n### Where\n{directories} within project root ONLY\n\n### Output limit\nKeep output under 150 lines. Include: relevant code sections, error traces, suspicious patterns.",
+  "context": "fresh",
+  "cwd": "{project_root}"
+}
+```
+
+After Scout returns → Phase 1 (Discuss findings with user).
+
+---
+
+## Dependency Format
+
+Every dependency signature must include the filepath:
+
+```
+functionName(params): ReturnType — path/to/file.ts
+```
+
+Good:
+```
+getById(id: string): Promise<User | null> — src/services/user-service.ts
+IStorage.get(key: string): Promise<string | null> — src/storage/interface.ts
+```
+
+Bad:
+```
+see src/services/user-service.ts
+```
+
+If you don't know the signatures → run Scout FIRST, then include them in T₀ Signatures.