Prompt — Repository Review (full reassessment / new-agent onboarding)
Two uses: (a) a full periodic reassessment producing a new Foundation, (b) onboarding a new agent or engineer through the Foundation.
Part A — Full reassessment
Operating rules
- Evidence before assertion. Documentation is a claim to verify, never evidence. Compare implementation, executed tests, direct observation, configuration, schema, infrastructure — then documentation last. Where sources conflict, record the conflict rather than silently choosing.
- Do not invent maturity. A capability is implemented only when the operational path exists. An interface, mock, design doc, commented-out block, roadmap entry or dormant module is not sufficient.
- Separate public from private. Internal assets keep full technical detail; public assets expose no secrets, internal paths, exploitable detail or operational weaknesses.
- Do not modify production behaviour. Add documentation, schemas and validation assets only. No refactoring, dependency upgrades, renames or infrastructure changes.
- Trace every material claim to a file path, symbol, test name, configuration key, schema, route or commit.
Sequence
1 — Inspect only. Cover: root documentation, manifests, dependencies, source directories, API routes, schemas and migrations, domain models, authentication and authorisation, data access, validation, error handling, logging and observability, background jobs, infrastructure-as-code, deployment, CI/CD, test structure, environment configuration, secrets handling, privacy and security controls, external integrations, ADRs, feature flags, and TODO/FIXME/deprecated paths. Inspect enough git history to find major decisions, replaced approaches, abandoned components and decisions documentation no longer reflects.
Produce a repository summary, components discovered, likely-authoritative files, obvious contradictions, areas requiring caution, and analysis confidence. Create no files yet.
2 — Present the generation plan. Files to create, files to amend, assumptions, information excluded from public assets, likely Foundation sections and Trust Wall claims, validation approach. Wait for approval.
3 — Generate. Foundation, internal assets, Trust Wall, validation tooling.
4 — Validate. Schemas parse; YAML/JSON valid; evidence paths resolve; public claims map to evidence; no secrets in public files; internal and public maturity agree; scripts execute.
5 — Report honestly. Files created and modified, validation results, claims safe to publish, claims withheld, unresolved contradictions, highest-risk gaps, recommended next action, exact rerun commands.
Standing cautions
These hold in every repository:
- Run the tests; do not read them. A test file proves nothing about a test outcome.
- Check current code, not commit history. A commit implementing a control does not mean the control exists now — a later merge can silently remove it.
- Treat
*_COMPLETE.md/*_SUMMARY.mdas historical. A filename asserting completion is a claim, not evidence. - Committed configuration is intent, never deployed state. Platform settings usually override it.
- Never print or copy secret values encountered during assessment. Record location, key path and category only.
Cautions specific to this repository
Not yet established — populate from the step 1 assessment.
Part B — New-agent onboarding
Explain the system through the Foundation
Read foundation/FOUNDATION.md first, then AGENTS.md. Understand, in order: what the system is and its lifecycle stage; its trust boundaries; its invariants and which are currently violated; the conventions; and what requires human review.
Correct extension points
| To do this | Go here |
|---|---|
| Add an endpoint | … |
| Add business logic | … |
| Change identity handling | … — review required |
| Change schema | … |
| Add background work | … |
Common architectural mistakes
Universal, and worth stating before the repository-specific list:
- Trusting the documentation. Verify against code first; check the contradiction register.
- Assuming tests protect you. Check whether an assertion exists before relying on one. If it does not, add it yourself.
- Assuming a capability is live because code exists. An interface, a mock, or an extensive but unregistered subsystem is not a capability.
- Removing a guard to make something work. If an authorisation attribute blocks you, the fix is a correct credential — not removing the attribute.
Repository-specific mistakes: populate from the contradiction and risk registers.
Evidence-backed guidance
When proposing a change, cite the file and line, the invariant it satisfies, the test asserting it, and whether the Foundation or ledger needs updating. Do not describe a change as safe because it "follows the existing pattern" — verify the pattern is the Foundation's, not merely a habit in a drifted area of the codebase.
Output (Part A)
Follow the five-step sequence, presenting results at each step. Do not create files before step 2 is approved. Prefer under-claiming to over-claiming at every step, and record what you could not determine rather than filling gaps with plausible inference.