Bootstrap Prompt Q1-Q7 Calibration

ELI5

Bootstrap is a structured interview. The agent reads your spec and your scaffold first, then asks seven questions whose answers it cannot guess. The interview stops you and the agent from agreeing on invariants neither of you grounded in evidence.

Technical Deep Dive

The interview shape

sequenceDiagram
  autonumber
  participant H as Human
  participant A as Bootstrap agent
  participant R as Repo (spec/scaffold)
  participant S as contract.schema.json

  H->>A: paste 00-bootstrap.md
  A->>R: read docs/spec/, README, scaffold tree
  A->>H: ground-truth report (stack, ambiguities Q*, gaps)
  H->>A: confirm or correct
  A->>H: Q1 anti-shapes (predict 2)
  H-->>A: confirm/edit/reject
  A->>H: Q2 phase decomposition (5-8 phases)
  H-->>A: order/scope edits
  A->>H: Q3 subagent roster (planner/implementer/auditor/reviewer + extras)
  H-->>A: ratify
  A->>H: Q4 project invariants I-1..I-N (each with spec citation)
  H-->>A: accept only grounded ones
  A->>S: derive Q6 (integrations) from schema (MR-15)
  A->>H: Q5 build/test commands, Q6 cross-repo deps, Q7 direct-push boundary
  H-->>A: answers
  A->>R: emit CLAUDE.md, MILESTONES.md, AGENTS.xml, docs/ scaffold
  A->>A: Phase 4 self-audit (rank DAG, M-ID xref, refusal conditions)
  A->>H: handoff: drift watches active, OPEN-N items, recommended next prompt

The seven questions

The “do not invent” guardrail

00-bootstrap.md opens with: “You are operating under a strict rule: do not invent invariants, milestones, or subagent roles you cannot ground in either (a) the spec docs in this repo, or (b) explicit answers I give you.” This is MR-9 in action and is the prompt’s load-bearing property: any new prompt or template addition must preserve it. If a generated artefact could contain an ungrounded claim, the prompt is broken.

The mechanism: every Phase 1 ambiguity becomes Q1, Q2, …; the human resolves them. Q4 is structured so the agent cannot declare an I-N without offering a spec citation, and the human refuses unsupported ones.

MR-15 — schema-bound bootstrap

Phase 6 of 00-bootstrap.md (the per-integration questions) is generated from contracts/contract.schema.json and verified equal in CI. The questions live in contracts/bootstrap-questions.yaml, a generated artefact:

# Generated by scripts/regen-bootstrap-questions.mjs — do not hand-edit.
schema_version: 1
questions:
  - integration: ares
    prompt_intent: |
      Does this repo intend to wire ares? Choose: yes (paste evidence) | not_applicable | pending.
    evidence_fields: [...]

Hand-editing the prompt without a corresponding schema change is a CI failure (MR-15 — defends MR-9 against ungrounded invariants entering via the bootstrap path).

Phase 4 self-audit

After generation, the agent self-audits five things:

1. Cross-reference — every M{N}.{n} in AGENTS.xml exists in MILESTONES.md; every cited invariant exists.
2. Rank graph — outranks: graph is a DAG; rendered as a Mermaid diagram in the bootstrap decision doc.
3. Inventory — every Q1–Q7 answer appears somewhere in the artefacts.
4. Refusal-condition — every subagent in AGENTS.xml has at least one <refusal_conditions> clause.
5. Date — every dated filename ISO-formatted; “Thursday”/“soon” body text converted or flagged.

Failed checks become OPEN-N items in the bootstrap decision doc.

Key Terms

• Ground-truth report — the Phase 1 deliverable: stack detection, spec summary, north-star extract (if any), Q* ambiguity list, scaffold-vs-spec delta.
• Drift watch — a named anti-shape from Q1 catalogued in docs/north-star/intent.md and consulted by the drift-watcher subagent.
• Bootstrap decision doc — docs/decisions/<TODAY_ISO>-bootstrap-complete.md; records ground-truth, Q1–Q7 answers, generated artefacts, and OPEN-N items.

Q&A

Q: Why does the prompt forbid the agent from inventing invariants? A: Because an ungrounded I-N corrupts every downstream phase — code comments cite it, decision docs reference it, the reviewer trusts it. MR-9 enforces “no invariant without citation”. The prompt’s job is to surface ambiguity as a question (Q*), not paper over it.

Q: Which of Q1-Q7 produces the project’s named drift watches? A: Q1. The agent predicts two anti-shapes from spec/scaffold, the human ratifies/edits, and the accepted ones land in docs/north-star/intent.md under drift_watches:. The drift-watcher subagent reads that list when adjudicating ambiguous changes.

Q: How does MR-15 keep Q1-Q7 from drifting from the schema? A: The integration-side questions (Phase 6 of the bootstrap) are auto-generated from contracts/contract.schema.json into contracts/bootstrap-questions.yaml. CI verifies the prompt and the generated YAML stay in sync. Hand-editing the prompt fails CI; the only legitimate path is to bump the schema and regenerate.

Examples

A bootstrap session for traceo-cat: ground-truth report flags Q1 (“spec mentions ‘baseline’ three times without defining it”) and Q2 (“§3.2 calls out a ‘verifier’ role unclear if it’s the same as the reviewer”). Operator answers, then ratifies anti-shapes (Q1: “treating baselines as test fixtures instead of versioned contracts”; “polishing the dashboard before the verify-loop converges”), invariants I-1..I-4 each with §-line citation. Generated CLAUDE.md is 187 lines; self-audit surfaces one OPEN-1 (CI provider not yet chosen — Q5 partial). Bootstrap decision doc records everything.