Project Mundial — World Cup 2026 Football Analysis

This project produces pure football analysis (no betting odds, no expert picks) for every World Cup 2026 match,
using a multi-agent pipeline with ensemble consensus and post-event validation. This document is the operator's
manual for running the pipeline end-to-end.

1. Read These First (mandatory)

Before running anything, read these methodology docs in this order:

2. Agents (7 total, in ~/.pi/agent/agents/)

Gathering layer (run in PARALLEL, model: MiniMax-M3)

Synthesis layer (run in PARALLEL, 3 models for ensemble)

⚙️ match-writer prompts are GENERATED, not hand-edited. Source of truth: agents-src/_core.md (shared body + calibration rules) + the thin variant files. Run node agents-src/build.mjs to regenerate .pi/agents/match-writer*.md (full system prompts, max adherence, compaction-safe). The build validates at build time — dead paths, unfilled tokens, YAML-unsafe frontmatter, and calibration-rule-count drift all fail the build. Flags: --diff (dry-run), --check (validation only). This is why the calibration rules are byte-identical across all 4 variants.

📍 agents-src/ lives in the PROJECT ROOT (not .pi/) — this avoids the safe-guard protected-path prompt on every _core.md edit. The build writes generated outputs to .pi/agents/ via bash/fs (which safe-guard doesn't intercept). The 4 gathering agents (match-scout, injury-sweeper, referee-profiler, post-event-scout) are hand-edited in .pi/agents/ (rarely changed).

📍 Agents live in the PROJECT (.pi/agents/), not global. They're mundial-specific. Invoke with agentScope: "project" (or "both") — the subagent tool defaults to "user" and won't find them otherwise. Generated match-writer*.md are .gitignored (rebuilt from source); the 4 gathering agents (match-scout, injury-sweeper, referee-profiler, post-event-scout) are hand-edited and committed.

Post-event layer (run AFTER kickoff)

Post-event workflow: post-event-scout (gather) → post-event-writer (review, rubric-scored) → lead publishes + updates team profiles + closes backlog task. The rubric (100-pt scale: Winner/Scoreline/Who-Scores/Findings/Model-breaking) lives in doc-1 § Post-Event Calibration Rubric. Adopted Jun 23 (TASK-97).

Model-qualified syntax: When invoking models, use provider-qualified names (zai/glm-5.1), never bare names
(bare glm-5.1 may resolve to an unauthenticated alias).

3. Source Directory Structure

Sources are split into canonical reference (stable, shared, de-duplicated) and per-match (match-specific application). Gathering agents write to BOTH — canonical profiles are updated, match dirs hold the thin match-specific delta.

sources/
├── reference/                          ← CANONICAL (stable, shared across matches)
│   ├── wc2026-full-schedule.md         (groups + schedule)
│   ├── referees/{surname}.md           (career profile + assignments log — UPDATED, not re-gathered)
│   └── venues/{city-slug}.md           (roof, capacity, altitude, climate-control — stable)
└── matches/{code1}-vs-{code2}/         ← PER-MATCH (thin delta + match-specific only)
    ├── scout/              ← match-scout output (H2H, THIS-opponent tactics, group math, match-day weather)
    ├── team-news-{t1}/     ← injury-sweeper output for team 1 (suspensions, fresh injuries, projected XI vs THIS opponent)
    ├── team-news-{t2}/     ← injury-sweeper output for team 2
    ├── referee/            ← match-specific application only (assignment + how THIS ref affects THIS matchup + discounted card/pen prediction)
    ├── weather/            ← (optional; match-day forecast with timestamp)
    ├── post-event/         ← always match-specific
    └── archive-superseded/ ← old/superseded files MOVED HERE (never delete)

Source hygiene rules:

• Writers read BOTH layers: their assigned match dir (thin delta) AND the canonical profiles for both teams + the referee + the venue. Canonical profiles are CURRENT and CURATED — they are not "contamination."
• Never cross-reference sibling match dirs (stale/contradictory intel = noise). This rule is about match-to-match contamination, NOT about reading canonical reference profiles.
• Canonical profiles are UPDATED (append-dated sections, never delete — audit trail). The first match to profile a ref/venue/team CREATES the canonical; subsequent matches UPDATE it + log the assignment.
• Superseded files go to archive-superseded/, never deleted.
• Match code convention: lowercase 3-letter codes, e.g. eng-vs-cro, por-vs-drc.

Phase status (Jun 18):

• ✅ Phase 1 LIVE — referees + venues canonical layer. 19 referee profiles + 7 venue profiles in sources/reference/. Gathering agents update canonical profiles + log assignments; match dirs hold only match-specific application.
• ✅ Phase 2 LIVE — teams canonical layer. sources/reference/teams/{code}.md holds stable team identity (squad, manager, tactical signature, GK, form), UPDATED per matchday. injury-sweeper creates/updates the canonical; match dir team-news-{code}/ holds only the thin per-match delta (suspensions, fresh injuries, projected XI vs THIS opponent). Writers read BOTH layers. Seeded with CZE + RSA (MD2); remaining teams get canonical profiles created lazily on their next analysis.

4. Full Pipeline — Pre-Match (the standard run)

Step 0: Task setup

backlog_task_edit <id> -s "In Progress" -a agent
mkdir -p sources/matches/{code1}-vs-{code2}/{scout,team-news-{t1},team-news-{t2},referee,weather}

Step 1: Gathering (3 agents in PARALLEL via subagent tool)

Fire all three gathering agents at once. Each writes to its subdirectory. Wait for all 3 to complete before synthesis.

Key things each agent MUST surface (these are model-breaking if missed):

• Roof open/closed (determines if Finding 11 weather penalty applies)
• Manager NAME + temperament (conservative vs aggressive — determines Finding 12 conservation)
• Group context (is this the strongest/weakest group opponent? → need-to-win flag)
• GK confirmation (GK changes are model-breaking — e.g. FRA-SEN Mendy vs Diaw ambiguity)
• Referee penalty rate (a high pen rate tilts the favorite's scoring mix — but present as a ~30-40% band, NOT a near-certainty; validated POR-DRC: 0.40-0.45 rate → 0 pens)
• Injuries in local languages (don't miss non-English sources)

Step 2: Decision graph (doc-5) — EACH WRITER resolves independently (NOT the lead)

⚡ CHANGED Jun 23 (TASK-99). Previously the lead pre-resolved the 6-step graph and passed a synthesis block to all writers. This produced artificially tight spreads (1pt) and suppressed genuine analytical disagreement (e.g., the Ronaldo-vs-Bruno Who Scores debate). Validated via POR-UZB controlled re-run: independent resolution gave a 5pt spread and surfaced a real scorer disagreement the pre-resolution had flattened.

The framework (doc-1 Findings + doc-5 graph) is mandatory and unchanged. What changed is WHO resolves it: each writer, not the lead. The lead's role becomes verification + reconciliation, not resolution.

Writers walk all 6 steps themselves (mandatory §6.5 output section, baked into _core.md via build):

1. Group context — standings, must-win flags, urgency asymmetry
2. Conservation (F12) — resolve the discount yourself with justification (defending champion → reduce; manager personality > tier; milestone = no conservation). Range 0–8%.
3. Weather × style (F11) — heat threshold (>28°C degrades pressing by 60'). Neutralized if roof closed.
4. Weather × defense stack — heat + low block + hot GK = DRAW. Heat + open shape = goals.
5. Temperament — coach discipline, executability of the game plan.
6. Synthesis — combine into final probability adjustments, show the math (naive → adjusted).

The lead's task template MUST NOT include a pre-resolved synthesis block. Replace it with: *"Walk doc-5's 6 steps yourself using doc-1's Findings + briefs + predictions-summary. State your resolution per step with reasoning. Do NOT anchor on any lead-provided number."

Step 3: Synthesis (3 writers in PARALLEL, independent resolution)

Fire all three match-writers (mm3/g4/g5) at once, each reading the SAME self-contained source dir. Each writer resolves the decision graph independently (Step 2 above) and produces its own probabilities + Who Scores list. Expect HONEST SPREADS — a 1pt spread is correlation (something's wrong); a 3–7pt spread is genuine uncertainty (correct ensemble behavior).

Step 4: Consensus document (you write this — RECONCILE, don't average)

Write {code1}-vs-{code2}-2026-consensus-ensemble.md:

• Reconcile with reasoning, don't blindly average. A 5pt spread means the match is genuinely uncertain — say so. Flag outliers (>10pts) with reasoning, don't just drop them.
• Note the spread explicitly ("spread: 5pt (70-75% POR) — honest uncertainty"). Narrow spreads (1-2pt) should now be rare and noteworthy; if you see one, suspect the writers anchored on a shared input and flag it.
• Reconcile scorelines (modal pick + runner-up)
• Reconcile Who Scores (consensus #1 + disagreement notes — if writers split on #1, that IS the finding; document both cases)
• Document the decision graph resolution (the convergence points + the disagreement points)
• TL;DR FIRST: 1 bold headline line (win% / scoreline / who scores) → 4–6 short bullets → 1 "Watch:" line

Step 5: Publish

gister {file}.md --group {code1}-vs-{code2}      # NEVER use --auto-tag
gister {mm3-file}.md --group {code1}-vs-{code2}
gister {g4-file}.md --group {code1}-vs-{code2}
gister {g5-file}.md --group {code1}-vs-{code2}
gister {consensus-file}.md --group {code1}-vs-{code2}

Links in summaries use relative gister slugs (/eng-vs-cro/eng-vs-cro-2026-consensus-ensemble), NOT absolute URLs or file paths.

Step 6: Close task

backlog_task_edit <id> --final-summary "..." -s Done

5. Post-Event Review (after the match)

After kickoff, run the post-event-scout agent to gather the 12 checklist categories, then write {code}-2026-post-event-review.md:

Mandatory 12 categories (no blanks — a blank category is a process failure):

1. Winner (was the consensus favorite correct?)
2. Exact scoreline (was it in the top 3?)
3. Who Scores (did the #1 pick score? ≥1 hit is the bar)
4. Weather (forecast vs actual — validate EVERY time)
5. Possession (use FINAL stats, never halftime)
6. xG
7. Cards / penalties (was the referee profile right?)
8. Lineup (did the predicted XI start?)
9. GK (was the confirmed GK correct? GK changes are model-breaking)
10. Substitutions (did the predicted sub risks materialize?)
11. Finding 12 (did conservation/not-conservation play out as predicted?)
12. Key learnings (what to calibrate?)

Always use FINAL stats, never halftime figures. (NED-JPN possession: 69% HT → 59.8% FT.)

Publish to the match group: gister {review}.md --group {code1}-vs-{code2}

6. Hard Rules & Constraints

7. Tools Quick Reference

8. File Naming Conventions

9. Known Model Calibration Patterns (from 30 ensemble matches, auto-extracted by agent-accuracy.mjs)

Updated Jun 26, 2026. Stats auto-extracted from TOML blocks + post-event reviews. See agent-accuracy-report.md for full narrative.

Division of labor (validated over 30 matches):

• g5 = best aggregate accuracy (69% winner, lowest avg dist 1.8). Best on routine favorites. NOT the blowout specialist (that label was wrong — all agents under-predict blowout margins).
• mm3 = draw/upset hedge (closest 15x, highest scorer hit 44%). Consistently runs highest draw band. Best on upset/draw days (ENG-GHA, SCO-MAR, TUR-PAR, GER-ECU).
• g4 = tight-favorite-exact specialist (17% exact, best on close games). Volume backbone (N=30, never absent). Contrarian — flags dead-rubber upsets (USA-TUR) + mutual draws (JPN-SWE) as live.

TASK-99 impact (Jun 23+): Average spread widened from ~2pt (pre-TASK-99, artificial anchoring) to 8.1pt (post-TASK-99, honest independence). TASK-99 makes the pipeline honest, not prescient — wide spreads flag uncertainty correctly, but upsets still live in the tail (0/3 agents called GER-ECU or USA-TUR, but the 18pt spread correctly signaled "uncertain").

Other patterns (validated):

• Unanimous #1 scorer picks with milestone motivation are high-confidence (Messi 18 WC goals, Mbappé tied Klose 16, Haaland 12-game streak, Ronaldo FIRST to score at 6 WCs — all braced). BUT requires a finishing mechanism (weak GK/pen band/mobility swap). Milestone alone = minutes not goals (Kane ENG-GHA 86' miss).
• Blowout underestimate is systematic (GER 7-1, NED 5-1, POR 5-0): all agents under-predict 4+ margins when elite attack + non-veteran-GK block. Weight 15-20% on 4+ margin.
• Draw epidemic has a boundary: applies when underdog has low block + hot GK, NOT when favorite has generational scorer + open-shape underdog.
• Referee leniency discount ~20-25% confirmed at tournaments. Some refs have INVERTED discounts (Makkelie = tournament card-happy, 5.50 Y/gm vs 2.57 career).

Instructions for the usage of Backlog.md CLI Tool

Backlog.md: Comprehensive Project Management Tool via CLI

Assistant Objective

Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata
remains fully synchronized and up-to-date.

Core Capabilities

• ✅ Task Management: Create, edit, assign, prioritize, and track tasks with full metadata
• ✅ Search: Fuzzy search across tasks, documents, and decisions with backlog search
• ✅ Acceptance Criteria: Granular control with add/remove/check/uncheck by index
• ✅ Definition of Done checklists: Per-task DoD items with add/remove/check/uncheck
• ✅ Board Visualization: Terminal-based Kanban board (backlog board) and web UI (backlog browser)
• ✅ Git Integration: Automatic tracking of task states across branches
• ✅ Dependencies: Task relationships and subtask hierarchies
• ✅ Documentation & Decisions: Structured docs and architectural decision records
• ✅ Export & Reporting: Generate markdown reports and board snapshots
• ✅ AI-Optimized: --plain flag provides clean text output for AI processing

Why This Matters to You (AI Agent)

1. Comprehensive system - Full project management capabilities through CLI
2. The CLI is the interface - All operations go through backlog commands
3. Unified interaction model - You can use CLI for both reading (backlog task 1 --plain) and writing (
   backlog task edit 1)
4. Metadata stays synchronized - The CLI handles all the complex relationships

Key Understanding

• Tasks live in backlog/tasks/ as task-<id> - <title>.md files
• You interact via CLI only: backlog task create, backlog task edit, etc.
• Use --plain flag for AI-friendly output when viewing/listing
• Never bypass the CLI - It handles Git, metadata, file naming, and relationships

⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI

ALL task operations MUST use the Backlog.md CLI commands

• ✅ DO: Use backlog task edit and other CLI commands
• ✅ DO: Use backlog task create to create new tasks
• ✅ DO: Use backlog task edit <id> --check-ac <index> to mark acceptance criteria
• ❌ DON'T: Edit markdown files directly
• ❌ DON'T: Manually change checkboxes in files
• ❌ DON'T: Add or modify text in task files without using CLI

Why? Direct file editing breaks metadata synchronization, Git tracking, and task relationships.

1. Source of Truth & File Structure

📖 UNDERSTANDING (What you'll see when reading)

• Markdown task files live under backlog/tasks/ (drafts under backlog/drafts/)
• Files are named: task-<id> - <title>.md (e.g., task-42 - Add GraphQL resolver.md)
• Project documentation is in backlog/docs/
• Project decisions are in backlog/decisions/

🔧 ACTING (How to change things)

• All task operations MUST use the Backlog.md CLI tool
• This ensures metadata is correctly updated and the project stays in sync
• Always use --plain flag when listing or viewing tasks for AI-friendly text output

2. Common Mistakes to Avoid

❌ WRONG: Direct File Editing

# DON'T DO THIS:

1. Open backlog/tasks/task-7 - Feature.md in editor
2. Change "- [ ]" to "- [x]" manually
3. Add notes or final summary directly to the file
4. Save the file

✅ CORRECT: Using CLI Commands

# DO THIS INSTEAD:
backlog task edit 7 --check-ac 1  # Mark AC #1 as complete
backlog task edit 7 --notes "Implementation complete"  # Add notes
backlog task edit 7 --final-summary "PR-style summary"  # Add final summary
backlog task edit 7 -s "In Progress" -a @agent-k  # Multiple commands: change status and assign the task when you start working on the task

3. Understanding Task Format (Read-Only Reference)

⚠️ FORMAT REFERENCE ONLY - The following sections show what you'll SEE in task files.
Never edit these directly! Use CLI commands to make changes.

Task Structure You'll See

---
id: task-42
title: Add GraphQL resolver
status: To Do
assignee: [@sara]
labels: [backend, api]
---

## Description

Brief explanation of the task purpose.

## Acceptance Criteria

<!-- AC:BEGIN -->

- [ ] #1 First criterion
- [x] #2 Second criterion (completed)
- [ ] #3 Third criterion

<!-- AC:END -->

## Definition of Done

<!-- DOD:BEGIN -->

- [ ] #1 Tests pass
- [ ] #2 Docs updated

<!-- DOD:END -->

## Implementation Plan

1. Research approach
2. Implement solution

## Implementation Notes

Progress notes captured during implementation.

## Final Summary

PR-style summary of what was implemented.

How to Modify Each Section

4. Defining Tasks

Creating New Tasks

Always use CLI to create tasks:

# Example
backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion"

Title (one liner)

Use a clear brief title that summarizes the task.

Description (The "why")

Provide a concise summary of the task purpose and its goal. Explains the context without implementation details.

Acceptance Criteria (The "what")

Understanding the Format:

• Acceptance criteria appear as numbered checkboxes in the markdown files
• Format: - [ ] #1 Criterion text (unchecked) or - [x] #1 Criterion text (checked)

Managing Acceptance Criteria via CLI:

⚠️ IMPORTANT: How AC Commands Work

• Adding criteria (--ac) accepts multiple flags: --ac "First" --ac "Second" ✅
• Checking/unchecking/removing accept multiple flags too: --check-ac 1 --check-ac 2 ✅
• Mixed operations work in a single command: --check-ac 1 --uncheck-ac 2 --remove-ac 3 ✅

# Examples

# Add new criteria (MULTIPLE values allowed)
backlog task edit 42 --ac "User can login" --ac "Session persists"

# Check specific criteria by index (MULTIPLE values supported)
backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3  # Check multiple ACs
# Or check them individually if you prefer:
backlog task edit 42 --check-ac 1    # Mark #1 as complete
backlog task edit 42 --check-ac 2    # Mark #2 as complete

# Mixed operations in single command
backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3

# ❌ STILL WRONG - These formats don't work:
# backlog task edit 42 --check-ac 1,2,3  # No comma-separated values
# backlog task edit 42 --check-ac 1-3    # No ranges
# backlog task edit 42 --check 1         # Wrong flag name

# Multiple operations of same type
backlog task edit 42 --uncheck-ac 1 --uncheck-ac 2  # Uncheck multiple ACs
backlog task edit 42 --remove-ac 2 --remove-ac 4    # Remove multiple ACs (processed high-to-low)

Definition of Done checklist (per-task)

Definition of Done items are a second checklist in each task. Defaults come from definition_of_done in the project config file (backlog/config.yml, .backlog/config.yml, or backlog.config.yml) or from Web UI Settings, and can be disabled per task.

Managing Definition of Done via CLI:

# Add DoD items (MULTIPLE values allowed)
backlog task edit 42 --dod "Run tests" --dod "Update docs"

# Check/uncheck DoD items by index (MULTIPLE values supported)
backlog task edit 42 --check-dod 1 --check-dod 2
backlog task edit 42 --uncheck-dod 1

# Remove DoD items by index
backlog task edit 42 --remove-dod 2

# Create without defaults
backlog task create "Feature" --no-dod-defaults

Key Principles for Good ACs:

• Outcome-Oriented: Focus on the result, not the method.
• Testable/Verifiable: Each criterion should be objectively testable
• Clear and Concise: Unambiguous language
• Complete: Collectively cover the task scope
• User-Focused: Frame from end-user or system behavior perspective

Good Examples:

• "User can successfully log in with valid credentials"
• "System processes 1000 requests per second without errors"
• "CLI preserves literal newlines in description/plan/notes/final summary; \\n sequences are not auto‑converted"

Bad Example (Implementation Step):

• "Add a new function handleLogin() in auth.ts"
• "Define expected behavior and document supported input patterns"

Task Breakdown Strategy

1. Identify foundational components first
2. Create tasks in dependency order (foundations before features)
3. Ensure each task delivers value independently
4. Avoid creating tasks that block each other

Task Requirements

• Tasks must be atomic and testable or verifiable
• Each task should represent a single unit of work for one PR
• Never reference future tasks (only tasks with id < current task id)
• Ensure tasks are independent and don't depend on future work

5. Implementing Tasks

5.1. First step when implementing a task

The very first things you must do when you take over a task are:

• set the task in progress
• assign it to yourself

# Example
backlog task edit 42 -s "In Progress" -a @{myself}

5.2. Review Task References and Documentation

Before planning, check if the task has any attached references or documentation:

• References: Related code files, GitHub issues, or URLs relevant to the implementation
• Documentation: Design docs, API specs, or other materials for understanding context

These are visible in the task view output. Review them to understand the full context before drafting your plan.

5.3. Create an Implementation Plan (The "how")

Previously created tasks contain the why and the what. Once you are familiar with that part you should think about a
plan on HOW to tackle the task and all its acceptance criteria. This is your Implementation Plan.
First do a quick check to see if all the tools that you are planning to use are available in the environment you are
working in.
When you are ready, write it down in the task so that you can refer to it later.

# Example
backlog task edit 42 --plan "1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test"

5.4. Implementation

Once you have a plan, you can start implementing the task. This is where you write code, run tests, and make sure
everything works as expected. Follow the acceptance criteria one by one and MARK THEM AS COMPLETE as soon as you
finish them.

5.5 Implementation Notes (Progress log)

Use Implementation Notes to log progress, decisions, and blockers as you work.
Append notes progressively during implementation using --append-notes:

backlog task edit 42 --append-notes "Investigated root cause" --append-notes "Added tests for edge case"

# Example
backlog task edit 42 --notes "Initial implementation done; pending integration tests"

5.6 Final Summary (PR description)

When you are done implementing a task you need to prepare a PR description for it.
Because you cannot create PRs directly, write the PR as a clean summary in the Final Summary field.

Quality bar: Write it like a reviewer will see it. A one‑liner is rarely enough unless the change is truly trivial.
Include the key scope so someone can understand the impact without reading the whole diff.

# Example
backlog task edit 42 --final-summary "Implemented pattern X because Reason Y; updated files Z and W; added tests"

IMPORTANT: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the
implementation.

• Creation phase: provide Title, Description, Acceptance Criteria, and optionally labels/priority/assignee.
• When you begin work, switch to edit, set the task in progress and assign to yourself
  backlog task edit <id> -s "In Progress" -a "...".
• Think about how you would solve the task and add the plan: backlog task edit <id> --plan "...".
• After updating the plan, share it with the user and ask for confirmation. Do not begin coding until the user approves the plan or explicitly tells you to skip the review.
• Append Implementation Notes during implementation using --append-notes as progress is made.
• Add Final Summary only after completing the work: backlog task edit <id> --final-summary "..." (replace) or append using --append-final-summary.

Phase discipline: What goes where

• Creation: Title, Description, Acceptance Criteria, labels/priority/assignee.
• Implementation: Implementation Plan (after moving to In Progress and assigning to yourself) + Implementation Notes (progress log, appended as you work).
• Wrap-up: Final Summary (PR description), verify AC and Definition of Done checks.

IMPORTANT: Only implement what's in the Acceptance Criteria. If you need to do more, either:

1. Update the AC first: backlog task edit 42 --ac "New requirement"
2. Or create a new follow up task: backlog task create "Additional feature"

6. Typical Workflow

# 1. Identify work
backlog task list -s "To Do" --plain

# 2. Read task details
backlog task 42 --plain

# 3. Start work: assign yourself & change status
backlog task edit 42 -s "In Progress" -a @myself

# 4. Add implementation plan
backlog task edit 42 --plan "1. Analyze\n2. Refactor\n3. Test"

# 5. Share the plan with the user and wait for approval (do not write code yet)

# 6. Work on the task (write code, test, etc.)

# 7. Mark acceptance criteria as complete (supports multiple in one command)
backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3  # Check all at once
# Or check them individually if preferred:
# backlog task edit 42 --check-ac 1
# backlog task edit 42 --check-ac 2
# backlog task edit 42 --check-ac 3

# 8. Add Final Summary (PR Description)
backlog task edit 42 --final-summary "Refactored using strategy pattern, updated tests"

# 9. Mark task as done
backlog task edit 42 -s Done

7. Definition of Done (DoD)

A task is Done only when ALL of the following are complete:

✅ Via CLI Commands:

1. All acceptance criteria checked: Use backlog task edit <id> --check-ac <index> for each
2. All Definition of Done items checked: Use backlog task edit <id> --check-dod <index> for each
3. Final Summary added: Use backlog task edit <id> --final-summary "..."
4. Status set to Done: Use backlog task edit <id> -s Done

✅ Via Code/Testing:

5. Tests pass: Run test suite and linting
6. Documentation updated: Update relevant docs if needed
7. Code reviewed: Self-review your changes
8. No regressions: Performance, security checks pass

⚠️ NEVER mark a task as Done without completing ALL items above

8. Finding Tasks and Content with Search

When users ask you to find tasks related to a topic, use the backlog search command with --plain flag:

# Search for tasks about authentication
backlog search "auth" --plain

# Search only in tasks (not docs/decisions)
backlog search "login" --type task --plain

# Search with filters
backlog search "api" --status "In Progress" --plain
backlog search "bug" --priority high --plain

Key points:

• Uses fuzzy matching - finds "authentication" when searching "auth"
• Searches task titles, descriptions, and content
• Also searches documents and decisions unless filtered with --type task
• Always use --plain flag for AI-readable output

9. Quick Reference: DO vs DON'T

Viewing and Finding Tasks

Modifying Tasks

10. Complete CLI Command Reference

Task Creation

Task Modification

Acceptance Criteria Management

Task Content

Multi‑line Input (Description/Plan/Notes/Final Summary)

The CLI preserves input literally. Shells do not convert \n inside normal quotes. Use one of the following to insert real newlines:

• Bash/Zsh (ANSI‑C quoting):
  • Description: backlog task edit 42 --desc $'Line1\nLine2\n\nFinal'
  • Plan: backlog task edit 42 --plan $'1. A\n2. B'
  • Notes: backlog task edit 42 --notes $'Done A\nDoing B'
  • Append notes: backlog task edit 42 --append-notes $'Progress update line 1\nLine 2'
  • Final summary: backlog task edit 42 --final-summary $'Shipped A\nAdded B'
  • Append final summary: backlog task edit 42 --append-final-summary $'Added X\nAdded Y'
• POSIX portable (printf):
  • backlog task edit 42 --notes "$(printf 'Line1\nLine2')"
• PowerShell (backtick n):
  • backlog task edit 42 --notes "Line1nLine2"`

Do not expect "...\n..." to become a newline. That passes the literal backslash + n to the CLI by design.

Descriptions support literal newlines; shell examples may show escaped \\n, but enter a single \n to create a newline.

Implementation Notes Formatting

• Keep implementation notes concise and time-ordered; focus on progress, decisions, and blockers.

• Use short paragraphs or bullet lists instead of a single long line.

• Use Markdown bullets (- for unordered, 1. for ordered) for readability.

• When using CLI flags like --append-notes, remember to include explicit
  newlines. Example:

  backlog task edit 42 --append-notes $'- Added new API endpoint\n- Updated tests\n- TODO: monitor staging deploy'
  

Final Summary Formatting

• Treat the Final Summary as a PR description: lead with the outcome, then add key changes and tests.
• Keep it clean and structured so it can be pasted directly into GitHub.
• Prefer short paragraphs or bullet lists and avoid raw progress logs.
• Aim to cover: what changed, why, user impact, tests run, and risks/follow‑ups when relevant.
• Avoid single‑line summaries unless the change is truly tiny.

Example (good, not rigid):

Added Final Summary support across CLI/MCP/Web/TUI to separate PR summaries from progress notes.

Changes:
- Added `finalSummary` to task types and markdown section parsing/serialization (ordered after notes).
- CLI/MCP/Web/TUI now render and edit Final Summary; plain output includes it.

Tests:
- bun test src/test/final-summary.test.ts
- bun test src/test/cli-final-summary.test.ts

Task Operations

Common Issues

Remember: The Golden Rule

🎯 If you want to change ANYTHING in a task, use the backlog task edit command.
📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.

Full help available: backlog --help