| name | architectural-proposals |
| description | Write evidence-based architectural proposals before implementation |
| domain | architecture, planning |
| confidence | high |
| source | template |
Context
Use this skill when a change needs alignment before code is written: new subsystems, major refactors, significant dependency choices, or changes that affect multiple areas of the project.
Patterns
Proposal structure
A strong proposal usually includes:
- Problem statement — what is not working today, with concrete evidence
- Proposed approach — the design, boundaries, and key technical choices
- Impact — what changes, what stays the same, and who is affected
- Risks and mitigations — likely failure modes and how to reduce them
- Scope — what is included now and what is intentionally deferred
- Open questions — decisions that still need input
Writing rules
- Ground claims in repo context, requirements, and observable constraints
- Prefer specific file paths, interfaces, data flows, and rollout steps over vague language
- Acknowledge trade-offs; do not present any option as perfect
- Separate facts, assumptions, and recommendations clearly
Decision framing
For each major choice, capture:
- Recommendation
- Alternatives considered
- Why the recommendation wins
- What validation is still needed
Risk documentation
For each important risk, record:
- Risk — specific failure mode
- Likelihood — low / medium / high
- Impact — low / medium / high
- Mitigation — concrete action to reduce risk
Examples
✓ Good:
- Documenting why a static JSON catalog is sufficient now and when a database would be needed later
- Comparing two hosting approaches and naming the operational trade-offs
- Explaining how a refactor preserves current behavior while changing internal structure
✗ Poor:
- "We can figure out the details later"
- "This will scale forever" without evidence
- Listing tasks without describing the underlying design
Anti-patterns
- Writing proposals with no evidence from the current codebase
- Hiding trade-offs to make a recommendation sound easier
- Mixing implementation details with unresolved product questions
- Starting major implementation work before the core decision is documented
