Architecture Survey
Find a small number of structural opportunities that would make future changes easier
without turning the survey into implementation.
Boundaries
- Treat the target repository as read-only. Do not edit source, tests, decisions, ADRs,
plans, records, or Git state.
- Do not run builds, packaging, deployment, destructive commands, or external actions.
- Prefer a named subsystem. If none is supplied, use a bounded recent-churn window to
select one narrow area; never perform an unbounded repository scan.
- Large files, high churn, and dependency counts are discovery leads, not findings.
- Start from exact files or the tracked index. Bound actual entries, content, output,
and elapsed time before broader reads; a glob or truncated output is not a read budget.
Method
- Freeze repository identity, scope, exclusions, and current project stage.
- Inspect at most 30 days or 30 commits and 50 related paths unless evidence justifies a
smaller explicit expansion.
- Trace candidates through callers, state/data flow, tests, and user-visible consumers.
- Apply the deletion test: a useful boundary concentrates complexity behind a smaller
interface; deleting a shallow wrapper should not leave the same complexity scattered.
- Check current decisions and rejected alternatives. Historical incidents are leads,
not current-source truth.
- Prove repeated consumer friction or a real seam before recommending work. An identity
or dependency update with no semantic delta should end as
no action.
An architecture or protection suggestion is not an implementation requirement or release
gate. If a real scope choice is needed, ask a short question with the practical tradeoff;
do not start the proposed work or override an explicitly reserved later-stage start.
Output
Return at most five candidates labeled Strong, Worth exploring, or Speculative.
For each, include files, observed friction, current seam, proposed deepening, expected
leverage, tests that become simpler, migration risk, confidence, and relation to existing
decisions. End with one recommendation or no action recommended, plus the heavy and
external stages not run. Implementation requires a separate authorized task.
For a bounded known-good/known-fail shape, read
the synthetic example.
1---2name: architecture-survey3description: Produce a bounded, read-only, evidence-backed architecture survey for a named subsystem before a planned major change. Do not use it as a refactor task or release gate.4---56# Architecture Survey78Find a small number of structural opportunities that would make future changes easier9without turning the survey into implementation.1011## Boundaries1213- Treat the target repository as read-only. Do not edit source, tests, decisions, ADRs,14 plans, records, or Git state.15- Do not run builds, packaging, deployment, destructive commands, or external actions.16- Prefer a named subsystem. If none is supplied, use a bounded recent-churn window to17 select one narrow area; never perform an unbounded repository scan.18- Large files, high churn, and dependency counts are discovery leads, not findings.19- Start from exact files or the tracked index. Bound actual entries, content, output,20 and elapsed time before broader reads; a glob or truncated output is not a read budget.2122## Method23241. Freeze repository identity, scope, exclusions, and current project stage.252. Inspect at most 30 days or 30 commits and 50 related paths unless evidence justifies a26 smaller explicit expansion.273. Trace candidates through callers, state/data flow, tests, and user-visible consumers.284. Apply the deletion test: a useful boundary concentrates complexity behind a smaller29 interface; deleting a shallow wrapper should not leave the same complexity scattered.305. Check current decisions and rejected alternatives. Historical incidents are leads,31 not current-source truth.326. Prove repeated consumer friction or a real seam before recommending work. An identity33 or dependency update with no semantic delta should end as `no action`.3435An architecture or protection suggestion is not an implementation requirement or release36gate. If a real scope choice is needed, ask a short question with the practical tradeoff;37do not start the proposed work or override an explicitly reserved later-stage start.3839## Output4041Return at most five candidates labeled `Strong`, `Worth exploring`, or `Speculative`.42For each, include files, observed friction, current seam, proposed deepening, expected43leverage, tests that become simpler, migration risk, confidence, and relation to existing44decisions. End with one recommendation or `no action recommended`, plus the heavy and45external stages not run. Implementation requires a separate authorized task.4647For a bounded known-good/known-fail shape, read48[the synthetic example](references/synthetic-example.md).
SeasonCake