|
| 1 | +# CCA2A Sprint Prompt Template |
| 2 | + |
| 3 | +> **READ BEFORE WRITING agent prompts** for any sprint that scopes new architectural work. |
| 4 | +> |
| 5 | +> This template captures the lessons learned from sprint-2 (PR #358/#359) and sprint-3 (PR #360/#361/sprint-3-rescope) about how to prevent the recurring failure modes. |
| 6 | +
|
| 7 | +## Failure modes captured to date |
| 8 | + |
| 9 | +1. **"Designing What's Already Built" anti-pattern** (sprint-2 itself; recurred in sprint-3 PR-A-1/PR-C-1/PR-D-1 specs) — agents propose new types/files for substrate that already ships |
| 10 | +2. **Wrong-repo error** (W7 sprint-2 → ndarray; W9 sprint-3 → ada-consciousness) — agents defer to `GITHUB_REPO` env var instead of explicit prompt |
| 11 | +3. **Race-with-merge** (PR #358/#359, PR #360/#361, this PR) — main thread corrections land after PR merge; need follow-up PR |
| 12 | +4. **Pattern letter divergence** (sprint-2 W2 invented A-G that conflicted with W1) — fixed by embedding canonical pattern letters in every prompt |
| 13 | + |
| 14 | +## Substrate-grep checklist (mandatory before any new spec) |
| 15 | + |
| 16 | +Before writing PR-X-Y spec for any pattern X, run: |
| 17 | + |
| 18 | +```python |
| 19 | +import os |
| 20 | +from github import Github, Auth |
| 21 | +tok = os.environ["GITHUB_TOKEN"].strip().strip('"').strip("'") |
| 22 | +g = Github(auth=Auth.Token(tok)) |
| 23 | +repo = g.get_repo("AdaWorldAPI/lance-graph") # CANONICAL — do not defer to GITHUB_REPO env |
| 24 | + |
| 25 | +# 1. Read tier-0 doc — current pattern X status |
| 26 | +tier0 = repo.get_contents(".claude/knowledge/tier-0-pattern-recognition.md", ref="main").decoded_content.decode() |
| 27 | +# Find Pattern X section; note SHIPPED / PARTIALLY SHIPPED / DESIGN PHASE status |
| 28 | + |
| 29 | +# 2. Read cross-source matrix — find Pattern X row |
| 30 | +cross = repo.get_contents(".claude/knowledge/pattern-recognition-cross-source.md", ref="main").decoded_content.decode() |
| 31 | +# Note: shipped substrate file:symbol citations |
| 32 | + |
| 33 | +# 3. Substrate grep — confirm cited substrate exists |
| 34 | +for path in cited_substrate_files: |
| 35 | + f = repo.get_contents(path, ref="main") |
| 36 | + # Verify symbols mentioned in tier-0 actually exist in the file |
| 37 | + |
| 38 | +# 4. TD-X check — read corresponding TD row in TECH_DEBT.md |
| 39 | +td = repo.get_contents(".claude/board/TECH_DEBT.md", ref="main").decoded_content.decode() |
| 40 | +# Find TD-X row; status must align with tier-0 |
| 41 | + |
| 42 | +# 5. Recent PR check — has this pattern been touched in the last 30 days? |
| 43 | +recent = list(repo.get_commits(since=datetime.now() - timedelta(days=30))) |
| 44 | +# Scan for commits mentioning Pattern X or its TD-X |
| 45 | +``` |
| 46 | + |
| 47 | +If any check reveals shipped substrate, the spec MUST cite it and re-scope to "extension of shipped" rather than "construction from scratch". |
| 48 | + |
| 49 | +## Wrong-repo guardrail (mandatory in every agent prompt) |
| 50 | + |
| 51 | +Every worker agent prompt should include this snippet: |
| 52 | + |
| 53 | +```python |
| 54 | +# WRONG-REPO GUARDRAIL: do not defer to GITHUB_REPO env var |
| 55 | +import os |
| 56 | +from github import Github, Auth |
| 57 | +tok = os.environ["GITHUB_TOKEN"].strip().strip('"').strip("'") |
| 58 | +g = Github(auth=Auth.Token(tok)) |
| 59 | +repo = g.get_repo("AdaWorldAPI/lance-graph") # CANONICAL — explicit, not env-driven |
| 60 | +assert repo.full_name == "AdaWorldAPI/lance-graph", \ |
| 61 | + f"WRONG REPO: got {repo.full_name}, expected AdaWorldAPI/lance-graph" |
| 62 | +``` |
| 63 | + |
| 64 | +This 8-line block has prevented zero wrong-repo errors so far (because it didn't exist). Going forward, every spawned agent should have it pre-pended to their write protocol. |
| 65 | + |
| 66 | +## Pattern letter discipline |
| 67 | + |
| 68 | +The canonical pattern letter assignment lives in: |
| 69 | +1. `.claude/plans/unified-ogit-architecture-v1.md` (W1 master, sprint-2) |
| 70 | +2. `.claude/patterns.md` Pattern Recognition Framework (W3 sprint-2) |
| 71 | +3. `.claude/knowledge/tier-0-pattern-recognition.md` (post-PR #359 corrected) |
| 72 | + |
| 73 | +Every worker agent prompt MUST embed the canonical 15-letter table inline. Do not invent new letters; do not re-letter substrate inventory items. |
| 74 | + |
| 75 | +If a worker discovers a genuinely new pattern, they MUST surface it as a meta-1-review escalation, not invent letter P / Q / etc. unilaterally. |
| 76 | + |
| 77 | +## Race-with-merge mitigation |
| 78 | + |
| 79 | +When the main thread (or meta agent) catches a defect AFTER the PR opens but BEFORE merge: |
| 80 | +1. Push the fix to the same sprint branch (PR will pick it up on next push) |
| 81 | +2. Comment on the PR with the fix summary so reviewer sees it before merge |
| 82 | +3. If the merge happens before the fix lands: open a follow-up PR off main (this is what PR #359/#361/this PR does) |
| 83 | + |
| 84 | +## Sprint scaffolding pattern |
| 85 | + |
| 86 | +Every sprint should pre-create: |
| 87 | +1. Branch (`claude/<sprint-N>-<scope>`) off main via pygithub |
| 88 | +2. SPRINT_LOG-N.md scaffolding at `.claude/board/sprint-log-N/SPRINT_LOG.md` (worker roster, deliverables table, coordination notes, **canonical pattern letters embedded**) |
| 89 | +3. Worker prompt template (this template) |
| 90 | + |
| 91 | +Then spawn 12+meta agents in parallel; each agent's prompt includes: |
| 92 | +- Sprint context (compact) |
| 93 | +- Their specific deliverable (file path, target size, acceptance criteria) |
| 94 | +- Wrong-repo guardrail snippet |
| 95 | +- Substrate-grep checklist |
| 96 | +- Canonical pattern letter table (inline, not by reference) |
| 97 | +- pygithub-first protocol with quote-stripped GITHUB_TOKEN |
| 98 | + |
| 99 | +## Cross-references |
| 100 | + |
| 101 | +- `.claude/knowledge/tier-0-pattern-recognition.md` — canonical pattern letters + status |
| 102 | +- `.claude/knowledge/pattern-recognition-cross-source.md` — A-O ↔ Pillars ↔ .grok/ ↔ shipped substrate matrix |
| 103 | +- `.claude/board/sprint-log-2/sprint-summary.md` — sprint-2 lessons (W2 invented pattern letters, W7 wrong-repo) |
| 104 | +- `.claude/board/sprint-log-3/sprint-summary.md` — sprint-3 lessons (W9 wrong-repo, recurring; specs over-scoped) |
| 105 | +- `.claude/patterns.md` Pattern Recognition Framework + Anti-Pattern subsection |
| 106 | + |
| 107 | +## Provenance |
| 108 | + |
| 109 | +Captured post-#360 review pass. Reviewer flagged: |
| 110 | +> "Suggested guardrail for the next sprint: bake into every worker prompt a first-action verify step — `git remote -v` (if local) or `mcp__github__get_me` + repo env confirmation before any write. Cost: ~10 LoC per prompt. Saves 1 wrong-repo-rev per sprint." |
| 111 | +
|
| 112 | +This template formalizes that guardrail + extends to substrate-grep + pattern-letter discipline. |
0 commit comments