@trohde/earos 1.0.0

package/assets/init/.agents/skills/earos-remediate/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: earos-remediate
+description: "Generate a prioritized improvement plan from an EAROS evaluation. Triggers on \"how do I fix this\", \"improve this artifact\", \"remediation plan\", \"how to pass EAROS\", \"fix the assessment\", \"improvement plan\", \"what's wrong with my architecture\", \"how to get a better score\", or any request to improve an artifact based on evaluation results."
+---
+
+# SKILL: earos-remediate
+
+Generate a prioritized, actionable improvement plan from an EAROS evaluation record.
+
+## References
+
+- Patterns and before/after examples: `references/remediation-patterns.md`
+- Output template: `references/output-template.md`
+- Rubric files: discovered at runtime via `earos.manifest.yaml`
+- Evaluation schema: `standard/schemas/evaluation.schema.json`
+
+---
+
+## Workflow
+
+### Step 1 — Load the evaluation record
+
+Ask the user to provide the evaluation record (file path or paste content).
+
+- Read the file if a path is given.
+- Identify: `rubric_id`, `profile_id`, `overlay_ids`, `status`, all criterion scores, gate results, dimension scores, and the narrative fields (`evidence`, `rationale`, `actions`).
+- If the record is missing required fields, note which ones and proceed with what is available.
+
+### Step 2 — Load the rubric files
+
+Read `earos.manifest.yaml` to locate the rubric(s) referenced by the evaluation record.
+
+For each referenced rubric (core + profile + overlays):
+- Load the YAML file.
+- Extract for every criterion: `id`, `question`, `gate`, `scoring_guide`, `examples.good`, `examples.bad`, `anti_patterns`, `remediation_hints`, `decision_tree`.
+
+This is the authoritative source for what "good" looks like. Do not rely on training data for rubric content.
+
+### Step 3 — Classify and prioritize issues
+
+Read `references/remediation-patterns.md` before this step.
+
+Triage every criterion that scored below 3 (or triggered a gate failure):
+
+**Tier 1 — Blockers** (fix these first; evaluation cannot pass until resolved)
+- Any criterion with a `critical` gate that failed (status = Reject)
+- Any criterion with a `major` gate that scored < 2 (caps status at Conditional Pass)
+
+**Tier 2 — High Impact** (most likely to change the overall status)
+- Criteria scored 0 or 1 (Absent / Weak)
+- Criteria in high-weight dimensions (weight >= 1.1)
+- The criterion closest to tipping a dimension above the 2.0 floor threshold
+
+**Tier 3 — Incremental** (polish, turn Conditional Pass into Pass)
+- Criteria scored 2 (Partial) — especially those where the gap to 3 is narrow
+- Dimension average between 2.4 and 3.2 (one bump in a criterion could cross the Pass threshold)
+
+**Tier 4 — N/A review** (challenge whether N/A was correctly applied)
+- Any criterion marked N/A — check the justification is sound
+
+Within each tier, order by: gate severity descending → weight descending → score ascending.
+
+### Step 4 — Generate remediation items
+
+For each prioritized criterion, produce a structured remediation entry using the rubric's own content:
+
+```
+Criterion: <id> — <question>
+Current score: <score>/4   Gate: <severity or none>
+What score 3 looks like: <scoring_guide["3"]>
+What score 4 looks like: <scoring_guide["4"]>
+Good example: <examples.good[0]>
+Anti-patterns to avoid: <anti_patterns>
+Decision path: <decision_tree excerpt>
+Specific fixes:
+  - <remediation_hints item 1>
+  - <remediation_hints item 2>
+  - [context-specific fix derived from the evaluation's rationale]
+Effort estimate: <Low | Medium | High>  (see references/remediation-patterns.md)
+```
+
+Derive effort from the gap and criterion complexity:
+- Score 3→4: Low (usually evidence and cross-referencing)
+- Score 2→3: Medium (content gaps to fill)
+- Score 0–1→3: High (structural rework required)
+- Gate failure on critical: High (non-negotiable)
+
+### Step 5 — Compute projected impact
+
+After fixing Tier 1 and Tier 2 items, estimate what the new status would be:
+- Recalculate dimension averages assuming target scores (conservative: assume score reaches the minimum needed, not the maximum possible).
+- Check gate conditions.
+- State the projected status: Pass / Conditional Pass / Rework Required.
+
+If the current status is Reject due to a critical gate, state clearly: fixing the gate failure is the prerequisite for any other improvements to matter.
+
+### Step 6 — Output the remediation plan
+
+Read `references/output-template.md` before producing output.
+
+Structure:
+1. Summary (current status, projected status after fixes, number of issues by tier)
+2. Tier 1 — Blockers (gate failures)
+3. Tier 2 — High Impact items
+4. Tier 3 — Incremental improvements
+5. Tier 4 — N/A review (if any)
+6. Quick wins (Tier 3 items that are Low effort — do these first)
+7. Next step: offer to run `earos-assess` on the revised artifact
+
+---
+
+## Operating Principles
+
+- **Rubric-anchored.** Every fix recommendation must cite the rubric's own `scoring_guide`, `examples.good`, or `remediation_hints`. Do not invent criteria or guidance not in the rubric.
+- **Triage ruthlessly.** A plan with 15 equal-priority items is useless. The output must be prioritized so the architect knows exactly where to start.
+- **Feasibility-aware.** Flag if a Tier 1 item requires organizational change (e.g., a governance decision) vs. document change.
+- **Evidence anchored.** Where the evaluation record includes evidence anchors, quote them back to the architect so they know exactly what text triggered the low score.
+- **Status awareness.** If the artifact is already a Conditional Pass and the architect's goal is Pass, focus on Tier 3. If it is Reject, Tier 1 is the only thing that matters.

package/assets/init/.agents/skills/earos-remediate/references/output-template.md

@@ -0,0 +1,199 @@
+# Output Template — EAROS Remediation Plan
+
+This file defines the structure and formatting for the remediation plan output. Read this before Step 5 (output).
+
+---
+
+## Prioritization Logic
+
+Before writing the plan, compute the following and display it in the Status Summary:
+
+1. **Current weighted overall score** (from the evaluation record `overall_score`)
+2. **Current status** (from the evaluation record `status`)
+3. **Score needed for next status tier:**
+   - To reach `conditional_pass` from `rework_required`: need overall ≥ 2.4, no critical gate failures
+   - To reach `pass` from `conditional_pass`: need overall ≥ 3.2, no dimension < 2.0, no critical gate failures
+   - To reach `conditional_pass` from `reject`: must first fix the critical gate failure, then meet the conditional_pass threshold
+4. **Gap:** how many average points needed across criteria — identify the specific criteria where improvement is most achievable given the rubric's level descriptors
+
+Show this calculation explicitly in the status summary so the author understands exactly what they are working toward.
+
+### How to identify status-tipping criteria
+
+To find score-2 criteria that tip the status:
+1. Take current overall score
+2. For each score-2 criterion, compute: what would the overall score be if this criterion became a 3?
+   - Delta per criterion = (score improvement × criterion weight) / total weight
+3. If the resulting score crosses a threshold (2.4 or 3.2), flag this criterion as "status-tipping"
+
+This makes the remediation plan strategic, not just a list of things to fix.
+
+---
+
+## Full Remediation Plan Template
+
+```markdown
+# EAROS Remediation Plan
+
+**Artifact:** [title from evaluation record]
+**Artifact Type:** [type]
+**Evaluation Record:** [evaluation_id]
+**Evaluation Date:** [date]
+**Current Status:** [status — use traffic light: 🔴 Reject / 🟠 Rework Required / 🟡 Conditional Pass]
+**Current Score:** [overall_score] / 4.0
+
+---
+
+## What Needs to Change
+
+[1–2 sentence summary of what is holding this artifact back, in plain language for the author.
+Not criterion IDs — synthesize. E.g.: "The artifact scores well on scope and stakeholder
+identification, but lacks decision rationale and compliance traceability, which are the
+primary blockers for a Conditional Pass."]
+
+**Score needed for [target status]:** [X.X] / 4.0 (current: [Y.Y])
+**Gap:** [+Z.Z points] — achievable by [brief description of where the points come from]
+
+---
+
+## Priority 1 — Fix Gate Failures First
+
+> ⚠️ These block passing regardless of your overall score. Fix these before anything else.
+
+[If no gate failures:]
+No gate failures identified. Proceed to Priority 2.
+
+[For each gate failure:]
+
+### [criterion_id]: [criterion question]
+**Gate severity:** CRITICAL / MAJOR
+**Effect:** [what this gate failure causes — e.g., "Status = Reject regardless of overall score"]
+**Current score:** [0–1] — [evaluator's rationale from the evaluation record]
+**Evidence gap:** [what the evaluator found missing]
+
+**What a passing score (≥ 2) looks like:**
+> [Quote or paraphrase the scoring_guide "2" level descriptor from the rubric YAML]
+
+**Good examples (from the rubric):**
+- [examples.good item 1 from the rubric YAML]
+- [examples.good item 2]
+
+**What to avoid:**
+- [anti_patterns item 1 from the rubric YAML]
+
+**Action:** [Specific, verb-first instruction. Reference the artifact section. Specify format.]
+
+**Effort:** [quick fix / moderate / significant rework]
+
+---
+
+## Priority 2 — Lift Low Scores (0–1)
+
+> These are the biggest drag on your overall score. Address in order of dimension weight.
+
+[For each score-0 or score-1 criterion, ordered by dimension weight descending:]
+
+### [criterion_id]: [criterion question]
+**Dimension:** [dimension name] (weight: [X.X])
+**Current score:** [0 or 1] — [evaluator's rationale]
+**Evidence gap:** [missing information from evaluation record]
+
+**What score 3 looks like:**
+> [Quote the scoring_guide "3" level descriptor from the rubric YAML]
+
+**Good examples (from the rubric):**
+- [examples.good from rubric YAML]
+
+**What to avoid:**
+- [anti_patterns from rubric YAML]
+
+**Action:** [Specific instruction]
+
+**Effort:** [quick fix / moderate / significant rework]
+
+---
+
+## Priority 3 — Status-Tipping Improvements
+
+> Improving these score-2 criteria would push your overall score across the [target status] threshold.
+
+[For each status-tipping score-2 criterion:]
+
+### [criterion_id]: [criterion question]
+**Current score:** 2
+**Impact:** Improving to 3 adds [+Z.Z] to overall score → new overall = [X.X] ([status change if applicable])
+**Evidence gap:** [what is present vs. what is missing]
+
+**What score 3 looks like:**
+> [scoring_guide "3" descriptor from rubric YAML]
+
+**Good examples (from the rubric):**
+- [examples.good from rubric YAML]
+
+**Action:** [Specific instruction]
+
+**Effort:** [quick fix / moderate / significant rework]
+
+---
+
+## Priority 4 — Incremental Improvements
+
+> These score-2 criteria improve the overall score but do not change the status tier on their own.
+> Address after Priority 1–3 if you are targeting a higher score within the same status tier.
+
+[Collapsed summary — offer to expand if user wants detail:]
+
+| Criterion | Current | Target | Estimated Effort |
+|-----------|---------|--------|-----------------|
+| [ID] | 2 | 3 | [effort] |
+| [ID] | 2 | 3 | [effort] |
+
+[Say: "Ask me to expand any of these and I'll provide the same detail as the sections above."]
+
+---
+
+## Effort Summary
+
+| Priority | Actions | Estimated Effort |
+|----------|---------|-----------------|
+| P1 — Gate failures | [N] | [effort range] |
+| P2 — Low scores (0–1) | [N] | [effort range] |
+| P3 — Status-tipping (score 2) | [N] | [effort range] |
+| P4 — Incremental (score 2) | [N] | [effort range] |
+| **Total to reach [target status]** | **[P1+P2+P3]** | **[range]** |
+
+---
+
+## Next Step
+
+Once these changes are made, re-run `earos-assess` on the updated artifact to verify the score improvement.
+
+For help writing specific sections, use the `earos-template-fill` skill.
+For help creating a new artifact from scratch, use the `earos-artifact-gen` skill.
+
+*Remediation plan generated from evaluation record [evaluation_id] using EAROS [rubric_ids].*
+```
+
+---
+
+## Formatting Rules
+
+1. **Gate failures always appear first** — even if they seem minor. Status is determined by gates before averages.
+2. **Show the math** — display the score delta calculation for status-tipping criteria. Authors need to see that fixing criterion X adds 0.3 to their overall score.
+3. **Verb-first actions** — every action starts with a verb: Add, Create, Replace, Extend, Document, Remove, Restructure. Not "You should consider adding".
+4. **Reference sections** — every action references where in the artifact to make the change. If the section doesn't exist yet, say "Add a new section titled X after Section Y".
+5. **Source from the rubric, not from general knowledge** — the `scoring_guide`, `examples.good`, `anti_patterns`, and `remediation_hints` fields in the rubric YAML are the authoritative source for what good looks like. Quote them.
+6. **Collapse Priority 4** — offer to expand rather than dumping all score-2 criteria at once. The most common mistake is overwhelming the author with 10 actions when they should focus on 3.
+7. **Traffic lights for status** — use 🔴 Reject, 🟠 Rework Required, 🟡 Conditional Pass, 🟢 Pass in the header.
+
+---
+
+## Tone Guidelines
+
+Write for the **artifact author**, not the evaluator. The evaluation record speaks the evaluator's language (criterion IDs, evidence classes, scores). The remediation plan speaks the author's language (sections, content, formats).
+
+- Evaluate → Remediate: "TRC-01 scored 1 due to absent driver-component mapping" → "Add a table in Section 3 that maps each business driver to the components that realize it"
+- Frame actions as achievable, not as indictments. "Add X" not "You failed to include X"
+- Be direct about gate failures — they genuinely block passing, and the author needs to understand that urgency
+
+The plan should feel like advice from a senior peer who has read the evaluation, read the rubric, and knows exactly what needs to change. Not a list of scores, and not generic architectural advice.

package/assets/init/.agents/skills/earos-remediate/references/remediation-patterns.md

@@ -0,0 +1,330 @@
+# Remediation Patterns — EAROS Remediation Skill
+
+This reference contains common improvement patterns per dimension, effort estimation guidance, and before/after examples. Read this before Step 3 (triage) and when generating actions for a specific dimension.
+
+---
+
+## How to Use This File
+
+For each priority criterion, find the matching dimension below. The patterns describe the most common root causes and fixes. They are templates — always tailor the action to reference the specific artifact sections and content identified in the evaluation record.
+
+---
+
+## Effort Estimation Guidelines
+
+Use these when assigning effort to each action:
+
+| Label | Meaning | Typical work |
+|-------|---------|-------------|
+| `quick fix` | < 1 hour | Add a missing table, label an existing diagram, add a sentence of justification, fill a missing metadata field |
+| `moderate` | Half day (3–5 hours) | Add a new section, create a stakeholder/traceability matrix, document quality attribute scenarios, write a decision rationale |
+| `significant rework` | 1+ days | Redesign a component boundary, produce a missing architectural view, restructure the scope definition, develop a full DR plan |
+
+**Key rule:** If the rubric's `scoring_guide` says "score 2 requires X and Y but you're missing Y", and Y is a table or a paragraph, that is typically a `quick fix` or `moderate`. If Y is a diagram or a new section that doesn't exist yet, that is `moderate` to `significant rework`.
+
+---
+
+## Dimension Patterns
+
+### D1 — Stakeholder Identification and Fit (STK-01)
+
+**Common root causes of low scores:**
+- Stakeholders listed by role title only, with no concerns or information needs documented
+- Missing key stakeholder groups (operations, security, compliance) that the architecture impacts
+- Stakeholder table exists but is disconnected from the architecture decisions
+
+**Pattern — Missing stakeholder table:**
+```
+Add a stakeholder table with columns: Role | Primary Concerns | Key Questions |
+How This Architecture Addresses Them. Include at minimum: sponsoring business unit,
+delivery/engineering team, operations team, and security/compliance representatives.
+```
+
+**Pattern — Stakeholders listed without concerns:**
+```
+Extend the existing stakeholder list to include a "concerns" column for each
+stakeholder. For each concern, add a cross-reference to the section of the document
+that addresses it. This transforms a nominal list into a decision-relevant index.
+```
+
+**Before (score 1):** "Stakeholders: Architecture Board, Development Team, Operations"
+
+**After (score 3):** Stakeholder table with role, primary concern, secondary concern, and a reference to the section that addresses each concern.
+
+**Effort:** `quick fix` if stakeholders are identified but concerns are missing; `moderate` if stakeholders themselves are incomplete.
+
+---
+
+### D2 — Scope and Boundaries (SCP-01)
+
+**Common root causes of low scores:**
+- Scope described in terms of business goals only, with no explicit technical boundary
+- Missing in-scope / out-of-scope list
+- System context diagram absent or not linked to the scope statement
+
+**Pattern — Absent scope boundary:**
+```
+Add a "Scope and Boundaries" section before Section 1 (or in the executive summary).
+Structure it as:
+  IN SCOPE: [list of systems, functions, data domains included]
+  OUT OF SCOPE: [explicit exclusions with a one-line rationale for each]
+  DEFERRED: [items acknowledged but explicitly not addressed in this version]
+This prevents scope creep during review and gives the architecture a clear review target.
+```
+
+**Pattern — Scope stated but no system context diagram:**
+```
+Add a C4 Level 1 context diagram (or equivalent) showing the system under design as
+a box, with all external actors and systems that interact with it. Label each
+relationship. This makes the scope statement visual and reviewable.
+```
+
+**Before (score 1):** "This architecture covers the payments platform."
+
+**After (score 3):** Explicit in-scope/out-of-scope list plus a context diagram showing the payments platform boundary and all integrating systems.
+
+**Effort:** `quick fix` for in/out-of-scope list; `moderate` for adding context diagram.
+
+---
+
+### D3 — Traceability (TRC-01)
+
+**Common root causes of low scores:**
+- Architecture decisions not linked to the business drivers that motivated them
+- Quality attribute requirements present but no mapping to how the architecture satisfies them
+- Multiple layers (capability → component → deployment) without cross-references
+
+**Pattern — Missing driver-to-component traceability:**
+```
+Add a traceability table in [Section X] with columns:
+  Business Driver / Requirement | Architectural Decision | Realizing Component(s) | Evidence
+For each row, link the driver (from Section 1) to the decision that responds to it
+(either inline or in an ADR reference) and the component(s) that implement it.
+```
+
+**Pattern — Quality attributes defined but not satisfied:**
+```
+For each quality attribute scenario in [Section Y], add a "Satisfied by" row that
+names the specific architectural mechanism (e.g., "Availability 99.9%: satisfied
+by active-active deployment in regions A and B, described in Section 5.3").
+```
+
+**Before (score 1):** Quality attribute targets listed in a table with no linkage to architecture decisions.
+
+**After (score 3):** Each quality attribute scenario has a mechanism reference, and the architecture section explicitly states how it satisfies it.
+
+**Effort:** `moderate` (building a traceability matrix from scratch). `quick fix` if cross-references just need to be added to existing content.
+
+---
+
+### D4 — Internal Consistency (CON-01)
+
+**Common root causes of low scores:**
+- Component names differ between diagrams and prose sections
+- Data flows in the sequence diagram contradict the component diagram interfaces
+- Scope statement includes elements not shown in any diagram
+
+**Pattern — Name inconsistency:**
+```
+Create a glossary or component index (can be a table) that lists every named
+component exactly once with its canonical name. Replace all alternate names or
+abbreviations in diagrams and prose with the canonical name. Treat this as the
+document's namespace.
+```
+
+**Pattern — Diagram-prose contradiction:**
+```
+Audit Section [X] against Diagram [Y]: for each component in the diagram, verify
+that the prose description uses the same name and describes the same interfaces.
+Note and resolve every discrepancy found. Common issue: the diagram was updated
+after the prose was written.
+```
+
+**Effort:** `quick fix` for renaming; `moderate` if diagrams need to be redrawn.
+
+---
+
+### D5 — Rationale and Decision Quality (RAT-01)
+
+**Common root causes of low scores:**
+- Architecture decisions stated without alternatives considered
+- Single option presented as though no choice existed
+- Tradeoffs acknowledged but not quantified or substantiated
+
+**Pattern — Missing alternatives:**
+```
+For each major architectural decision in [Section X], add an "Alternatives Considered"
+subsection with:
+  Option A: [name] — [one-line description] — Rejected because [reason]
+  Option B: [name] — [one-line description] — Rejected because [reason]
+  Selected: [name] — [rationale tied to the driving constraints]
+This documents that a real choice was made, not just a default selection.
+```
+
+**Pattern — Tradeoffs stated but not evidenced:**
+```
+Replace vague tradeoff statements ("this approach offers better scalability") with
+quantified or observable claims ("this approach scales horizontally without schema
+migration, which satisfies the 10× traffic growth requirement from Business Driver 3 —
+validated in load test from [date/link]").
+```
+
+**Before (score 1):** "We chose Kafka for messaging."
+
+**After (score 3):** Decision section with the driving requirement, two alternatives with rejection rationale, and the selected option linked to a specific non-functional requirement.
+
+**Effort:** `moderate` per decision. If 3+ decisions need this treatment: `significant rework`.
+
+---
+
+### D6 — Compliance and Governance Fit (CMP-01)
+
+**Common root causes of low scores:**
+- No reference to mandatory standards, policies, or control frameworks
+- Compliance section present but not linked to specific architecture decisions
+- Security or data controls described generically without mapping to requirements
+
+**Pattern — Missing compliance references:**
+```
+Add a "Standards and Compliance" section listing:
+  - Applicable standards: [e.g., ISO 27001, PCI DSS, internal policy X]
+  - For each standard: which sections of this architecture address it
+  - Controls implemented: [list with mechanism and location in the design]
+  - Controls deferred: [list with owner and target date]
+```
+
+**Pattern — Compliance section exists but not connected:**
+```
+For each compliance requirement in [Section X], add a "Satisfied by" reference
+pointing to the specific component or mechanism in the architecture that implements
+it. A compliance section that lists requirements without showing how the architecture
+satisfies them scores 1, not 2.
+```
+
+**Effort:** `moderate` if compliance requirements are known but not documented; `significant rework` if the architecture has unaddressed control gaps.
+
+---
+
+### D7 — Maintainability and Evolution (MNT-01)
+
+**Common root causes of low scores:**
+- No version history or changelog
+- Owner not named
+- No documented process for updating the artifact
+
+**Pattern — Missing metadata:**
+```
+Add a document control table at the top of the artifact:
+  Title | Version | Status | Owner | Last Updated | Review Date
+  Change Log:
+    [version] | [date] | [author] | [change summary]
+This is a quick fix that immediately improves MNT-01.
+```
+
+**Effort:** `quick fix` — this is almost always a metadata gap, not a content gap.
+
+---
+
+### D8 — Actionability (ACT-01)
+
+**Common root causes of low scores:**
+- No next steps or implementation guidance
+- Recommendations listed without owners or timelines
+- Decision-ready content buried in appendices without a clear summary
+
+**Pattern — Missing next steps:**
+```
+Add a "Next Steps and Implementation Guidance" section at the end of the document:
+  - Immediate actions (within sprint / next 2 weeks)
+  - Decisions outstanding (with owner and deadline)
+  - Assumptions that need validation before implementation begins
+  - Dependencies on external teams or systems
+```
+
+**Effort:** `quick fix` to `moderate` depending on whether implementation guidance already exists in fragments.
+
+---
+
+### D9 — Clarity and Communication (CLR-01)
+
+**Common root causes of low scores:**
+- Dense jargon without a glossary
+- Diagrams present but not explained in prose
+- No executive summary for non-technical stakeholders
+
+**Pattern — Missing executive summary:**
+```
+Add a 1-page executive summary at the beginning that covers:
+  - What problem this architecture solves (1–2 sentences)
+  - The key design decisions and their rationale (3–5 bullets)
+  - What this means for delivery (timeline, risks, dependencies)
+This makes the document accessible to stakeholders who will not read the full detail.
+```
+
+**Pattern — Diagrams without prose explanation:**
+```
+For each diagram in the document, add a numbered walkthrough immediately below it
+(e.g., "① The API gateway receives the request → ② Routes to the appropriate
+microservice → ③ ..."). This forces the author to validate the diagram and
+dramatically improves reviewer comprehension.
+```
+
+**Effort:** `quick fix` for glossary and diagram walkthroughs; `moderate` for executive summary.
+
+---
+
+## Cross-Cutting Patterns
+
+### Adding a traceability matrix (general)
+
+A traceability matrix is the single highest-value addition to most architecture artifacts. The minimum viable version:
+
+| Source | Criterion Addressed | Document Section | Evidence Type |
+|--------|-------------------|-----------------|---------------|
+| Business Driver 1 | TRC-01, RAT-01 | Section 2.1 | Observed |
+| NFR: 99.9% availability | ACT-01, RA-QA-01 | Section 4.3 | Observed |
+| Compliance: PCI DSS Req 6 | CMP-01 | Section 6.2 | Observed |
+
+### Adding quality attribute scenarios (QAS)
+
+Quality attribute scenarios should follow this format (from ISO 25010 / ATAM):
+
+```
+Scenario ID: QAS-001
+Quality Attribute: Availability
+Stimulus: Hardware failure in primary region
+Response: Automatic failover to secondary region
+Measure: Recovery time < 5 minutes, zero data loss
+Architectural Mechanism: Active-active multi-region deployment (Section 5.2)
+Validation: Load test results from [date]
+```
+
+### Adding an ADR reference
+
+When the evaluator flags missing decision rationale, the fastest fix is to reference or attach an ADR. If ADRs don't exist, create a simplified inline version:
+
+```
+Decision: [Name]
+Date: [YYYY-MM-DD]
+Status: Accepted
+Context: [Why a decision was needed]
+Options: [Option A] vs [Option B] vs [Selected]
+Decision: [Selected option]
+Rationale: [Why — linked to a specific driver or constraint]
+Consequences: [Trade-offs accepted]
+```
+
+---
+
+## Effort by Status Transition
+
+Use this to set expectations with the author before they start:
+
+| Current Status | Target Status | Typical Work |
+|---------------|--------------|-------------|
+| Rework Required | Conditional Pass | Fix gate failures + lift 2–3 criteria from 1→2. Usually 1–2 days. |
+| Rework Required | Pass | Fix all gates + significant improvements across multiple criteria. Usually 3–5 days. |
+| Conditional Pass | Pass | Targeted improvements on 2–3 criteria at score 2. Usually half day to 1 day. |
+| Reject (critical gate) | Conditional Pass | Must fix the critical gate failure. Can be quick fix or significant rework depending on the criterion. |
+
+The single most impactful action is almost always fixing a gate failure or lifting a score-0 criterion to score-2. Do not invest effort improving a score-3 criterion to score-4 when score-0 criteria remain unaddressed.