| name | system-analysis |
| description | Use when analysing feasibility, dependency impact, and sketching API for new features. Load during the Analysis phase of SDLC. |
system-analysis
SDLC Phase: Analysis
Analyse requirements, determine feasibility, and map dependency impact.
Principles
- Understand the dependency graph — Every change has a ripple effect. Trace all crates that could be affected.
- No circular dependencies — The dependency graph must remain a DAG. If a change would introduce a cycle, the shared contract belongs in
rvlibs.
- Safe Rust only — Verify the change can be implemented without
unsafe. If unsafe is unavoidable, it must be documented and justified.
- Minimal external deps — Each new external dependency adds maintenance burden. Question every addition.
Analysis Dimensions
Dependency Impact
Map the change against the dependency graph:
- Which crates need to change? (direct changes)
- Which crates are affected indirectly? (consumers of changed APIs)
- Could this create a circular dependency? If yes, shared types go in
rvlibs.
- Will this require a new public API? If so, document the signatures.
Feasibility
Evaluate implementation viability:
- Safe Rust — Can this be implemented with safe Rust only? If unsafe is needed, what invariants must be upheld?
- Dependencies — Does this require new external dependencies? Are they well-maintained, widely used, and license-compatible?
- MSRV — Check the minimum supported Rust version for affected crates (see
docs/conventions.md). Does the approach require newer Rust features?
- Performance — Are there performance requirements or constraints? Does the approach have known performance characteristics?
API Sketch
Before implementation, sketch the public API:
- New types, traits, and their methods
- New function signatures
- How existing APIs change (additions, deprecations, removals)
- Whether the changes are backward compatible
Backward Compatibility
- Will existing code break? If so, can the change be introduced compatibly?
- Can the old and new APIs coexist during a migration period?
- If breaking, what is the migration path for users?
Crate Alignment
- Does the feature belong in the right crate according to the brain/body separation?
- Does it follow the crate's established patterns?
- Does it respect the "not preemptive" principle? (Do not create new crates speculatively.)
When to Stop and Confirm
Analysis may uncover issues that require human judgement:
- A circular dependency that needs a new shared type in
rvlibs
- A need for
unsafe code
- A new external dependency
- A breaking API change
- A feature that crosses crate boundaries in unexpected ways
When such an issue is found, stop and present the finding to the user. Do not proceed to design or implementation without confirmation.
Output Requirements
- An analysis report covering: dependency impact, feasibility, API sketch, backward compatibility, and crate alignment
- Any issues requiring human judgement clearly flagged
- If the analysis confirms feasibility, a clear path to the design phase