foomakers/assess-architecture

/assess-architecture — Architecture Assessment

Evaluate and decide on the system architecture pattern. Follows the resolution cascade: explicit argument wins, then existing adoption, then full assessment from guidelines.

Arguments

| Argument | Required | Description | | --------- | -------- | --------------------------------------------------------------------------- | | $choice | No | Override: skip assessment, use this architecture directly (e.g. hexagonal) |

Composed Skills

| Skill | Type | Required | | ------------------ | ---------- | ------------------------------------------------- | | /record-decision | Capability | Yes — records architecture decision as ADR |

Adoption File

• Target: adoption/tech/architecture.md
• Ownership: Full file (sole owner)

Algorithm

Step 1: Resolution Cascade

Path A — Argument Override

1. Check: Is $choice provided?

2. Skip: If not provided, go to Path B.

3. Act: Confirm the choice with the developer:

   Architecture override: $choice. This will be adopted without full assessment. Confirm?

4. Check: Does an adoption file already exist with a different pattern?

   • If yes, warn: "Current adoption is [existing]. Override to $choice?"

5. Verify: Developer confirms. Proceed to Step 2.

Path B — Adoption Exists

1. Check: Does adoption/tech/architecture.md exist and is it populated (not template)?

2. Skip: If not populated or missing, go to Path C.

3. Act: Read current adoption. Present:

   Architecture already adopted: [pattern name]. Adoption file is current and valid.

4. Check: Does a corresponding decision record exist? (Scan adoption/tech/adr/ for *architecture* files.)

5. Act: If decision record missing, compose /record-decision to backfill.

6. Verify: Adoption and decision record consistent. Done — exit skill.

Path C — Full Assessment

1. Act: Proceed to Step 2 (full assessment mode).

Step 2: Read Guidelines

1. Act: Read architecture guidelines:
   • Architecture README — decision tree, complexity matrix, selection criteria
   • Architectural Patterns — pattern descriptions and trade-offs
   • Project Constraints — team, platform, deployment constraints
2. Act: If PRD exists, read adoption/product/PRD.md for project context (team size, scale, compliance).
3. Verify: Guidelines and project context loaded.

Step 3: Evaluate Options

1. Act: Apply the Architecture Complexity Matrix from guidelines against project constraints:

   • Score each candidate pattern on: Implementation Complexity, Team Skill Required, Maintenance Overhead, Scalability, Best For.
   • Weight criteria based on project type (from PRD or developer input).

2. Act: If two or more patterns score within 10% of each other, present top 2 with trade-off analysis:

   Top candidates:

   1. [Pattern A] — Score: X. Strengths: ... Weaknesses: ...
   2. [Pattern B] — Score: Y. Strengths: ... Weaknesses: ...

   Recommendation: [Pattern A] because [reason].

3. Act: If one pattern clearly wins, present recommendation:

   Recommendation: [Pattern]

   • Rationale: [evidence from constraints and matrix]
   • Trade-offs: [key trade-offs acknowledged]

4. Verify: Developer approves the choice.

Step 4: Write Adoption File

1. Check: Does adoption/tech/architecture.md exist?
2. Act: Write or update the adoption file with the chosen pattern:
   • Concise, prescriptive statements (what IS adopted, not options)
   • Reference guidelines for detailed rationale
   • Preserve existing content in other sections if file already exists
3. Verify: Adoption file written and consistent.

Step 5: Record Decision

1. Act: Compose /record-decision:
   • $type: architectural
   • $topic: architecture-pattern
   • $summary: "[Pattern] adopted as system architecture"
2. Verify: ADR created at adoption/tech/adr/YYYY-MM-DD-architecture-pattern.md. Adoption file consistent with ADR.

Output Format

ASSESSMENT COMPLETE:
├── Domain:    Architecture
├── Path:      [Argument Override | Adoption Exists | Full Assessment]
├── Decision:  [pattern name]
├── Adoption:  [adoption/tech/architecture.md — written | confirmed | updated]
├── Record:    [ADR path — created | exists | backfilled]
└── Status:    [Complete | Confirmed existing]

Composition Interface

When composed by /bootstrap:

• Input: /bootstrap invokes /assess-architecture during Phase 2 (checklist completion). May pass $choice if developer pre-selected.
• Output: Returns decision summary and adoption file path.
• /bootstrap includes adoption and ADR changes in the next commit.

When invoked independently:

• Full interactive flow. Developer commits changes when satisfied.

Edge Cases

• Argument conflicts with adoption: Warn developer, ask for confirmation. If confirmed, update adoption and create new decision record (supersedes previous).
• Adoption file partially exists (e.g. has some sections but missing architecture pattern): Fill gap, preserve existing content.
• No PRD available: Proceed with assessment using developer-provided constraints. Warn: "No PRD found — relying on developer input for project context."
• Decision record already exists for same scope+decision: Skip writing (no duplicates).

Graceful Degradation

• If architecture guidelines are not found, use minimal decision framework: ask developer to choose between Modular Monolith, Hexagonal, and Microservices based on team size and scale needs.
• If /record-decision is not installed, warn and skip decision recording: "Decision not recorded — /record-decision not installed."
• If adoption directory doesn't exist, create it on first write.

Notes

• This skill establishes the base pattern for all assess-* skills: resolution cascade + guidelines reference + adoption write + /record-decision composition.
• Architecture decisions are architectural type → always produce ADR (never ADL).
• The resolution cascade IS the idempotency mechanism: if adoption exists, assessment is already done.
• Educational content (pattern descriptions, trade-offs, WHY) stays in guidelines. This skill references guidelines for decision matrices and scoring.