# Architecture Survey

> 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.

- Skill: `seasoncake/architecture-survey` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add seasoncake/architecture-survey`
- Raw SKILL.md: https://api.skillmd.com/api/skills/seasoncake/architecture-survey/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: SeasonCake (https://skillmd.com/u/seasoncake)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/seasoncake/architecture-survey

---


# 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

1. Freeze repository identity, scope, exclusions, and current project stage.
2. Inspect at most 30 days or 30 commits and 50 related paths unless evidence justifies a
   smaller explicit expansion.
3. Trace candidates through callers, state/data flow, tests, and user-visible consumers.
4. Apply the deletion test: a useful boundary concentrates complexity behind a smaller
   interface; deleting a shallow wrapper should not leave the same complexity scattered.
5. Check current decisions and rejected alternatives. Historical incidents are leads,
   not current-source truth.
6. 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](references/synthetic-example.md).