jumpstart-mode 1.1.13 → 1.1.14

package/.github/skills/api-version-migration/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: api-version-migration
+description: >
+  Plan and implement API version migrations (v1 to v2+) with compatibility analysis,
+  deprecation policy, rollout sequencing, and client-safe transition artifacts. Use whenever
+  the user asks to version an API, migrate clients, deprecate endpoints, or reduce
+  upgrade risk, even if they only ask "how do we move to v2 safely?"
+argument-hint: 'Describe current API version, target version, breaking changes, client types, and migration window.'
+---
+
+# API Version Migration Skill
+
+Create implementation-ready migration plans that protect existing clients while enabling new API capabilities.
+
+## Reference Index
+
+| Topic | File | Load When |
+|---|---|---|
+| Migration strategy choices | [references/migration-strategies.md](./references/migration-strategies.md) | Choosing cutover pattern |
+| Change classification matrix | [references/change-classification.md](./references/change-classification.md) | Identifying breaking changes |
+| Deprecation and communication policy | [references/deprecation-policy.md](./references/deprecation-policy.md) | Setting sunset timelines |
+
+## Template Index
+
+| Template | File |
+|---|---|
+| Migration plan | [templates/migration-plan-template.md](./templates/migration-plan-template.md) |
+| Client compatibility matrix | [templates/client-compatibility-matrix.md](./templates/client-compatibility-matrix.md) |
+
+## Example Index
+
+- [examples/v1-to-v2-migration-example.md](./examples/v1-to-v2-migration-example.md)
+
+## Procedure
+
+1. Inventory current API usage by endpoint and consumer type.
+2. Classify all proposed changes using [references/change-classification.md](./references/change-classification.md).
+3. Choose migration strategy with [references/migration-strategies.md](./references/migration-strategies.md).
+4. Define compatibility artifacts:
+   - versioning path
+   - fallback behavior
+   - adapters or shims
+   - deprecation schedule
+5. Build phased rollout plan with entry and exit criteria.
+6. Define telemetry and SLO checks for migration health.
+7. Publish migration guide and client communication timeline.
+
+## Required Outputs
+
+- Breaking vs non-breaking change table
+- Migration approach recommendation
+- Compatibility matrix
+- Deprecation timeline
+- Rollout and rollback plan
+- Testing plan (contract + regression)
+- Operational monitoring plan
+
+## Trigger Phrases
+
+- "migrate v1 to v2"
+- "API deprecation plan"
+- "breaking changes strategy"
+- "versioning roadmap"
+- "safe API cutover"
+
+## Evaluation Starter
+
+Use [evals/evals.json](./evals/evals.json) as starter prompts.
+
+## Automated Assertion Grading
+
+Use [scripts/assertion_runner.py](./scripts/assertion_runner.py) to produce benchmark-friendly grading output.
+
+```bash
+python .github/skills/api-version-migration/scripts/assertion_runner.py \
+  --evals .github/skills/api-version-migration/evals/evals.json \
+  --eval-id 1 \
+  --output output.txt \
+  --result grading.json
+```

package/.github/skills/api-version-migration/evals/evals.json

@@ -0,0 +1,74 @@
+{
+  "skill_name": "api-version-migration",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Build a migration plan to move a public API from v1 to v2 with parallel support and deprecation policy.",
+      "expected_output": "Phased migration plan with compatibility matrix and sunset schedule.",
+      "assertions": [
+        {
+          "name": "phased_rollout_present",
+          "type": "contains_concept",
+          "description": "Plan includes phased rollout rather than one-step cutover."
+        },
+        {
+          "name": "deprecation_timeline_included",
+          "type": "contains_concept",
+          "description": "Plan includes explicit deprecation and sunset timeline."
+        },
+        {
+          "name": "client_compatibility_matrix",
+          "type": "contains_concept",
+          "description": "Plan includes client compatibility view or matrix guidance."
+        }
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Classify these API contract changes as breaking or non-breaking and propose mitigations.",
+      "expected_output": "Change classification table with clear mitigations.",
+      "assertions": [
+        {
+          "name": "breaking_change_detection",
+          "type": "contains_concept",
+          "description": "Output identifies breaking change categories correctly."
+        },
+        {
+          "name": "mitigation_per_change",
+          "type": "contains_concept",
+          "description": "Output maps each change to a mitigation strategy."
+        },
+        {
+          "name": "affected_clients_considered",
+          "type": "contains_concept",
+          "description": "Output considers affected client groups in prioritization."
+        }
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Design rollback criteria and migration monitoring for an API version cutover.",
+      "expected_output": "Operational controls with objective rollback triggers.",
+      "assertions": [
+        {
+          "name": "objective_rollback_triggers",
+          "type": "contains_concept",
+          "description": "Output defines measurable rollback thresholds."
+        },
+        {
+          "name": "monitoring_signals_defined",
+          "type": "contains_concept",
+          "description": "Output defines migration health signals such as error rate and client failures."
+        },
+        {
+          "name": "operational_ownership_defined",
+          "type": "contains_concept",
+          "description": "Output clarifies ownership for migration monitoring and response."
+        }
+      ],
+      "files": []
+    }
+  ]
+}

package/.github/skills/api-version-migration/examples/v1-to-v2-migration-example.md

@@ -0,0 +1,24 @@
+# Example: v1 to v2 Migration
+
+## Context
+
+- v1 widely used by mobile apps and partner integrations.
+- v2 introduces stricter request schemas and new auth scopes.
+
+## Strategy
+
+- Run v1 and v2 in parallel for 120 days.
+- Add v1 compatibility adapter for changed response fields.
+- Provide per-client migration dashboard.
+
+## Key Controls
+
+- Deprecation headers on all v1 responses.
+- Weekly report of remaining v1 traffic by client.
+- Rollback if v2 error rate exceeds threshold.
+
+## Exit Criteria
+
+- 95% client traffic on v2.
+- No unresolved critical client blockers.
+- Signed-off deprecation notices for remaining clients.

package/.github/skills/api-version-migration/references/change-classification.md

@@ -0,0 +1,29 @@
+# Change Classification
+
+## Breaking Changes
+
+- Removing endpoints
+- Removing response fields
+- Making optional input required
+- Changing field types
+- Changing business semantics on existing operations
+
+## Potentially Breaking
+
+- New enum values where clients assume closed sets
+- New auth requirements on existing endpoints
+- Pagination behavior changes
+
+## Non-Breaking
+
+- New optional request fields
+- New optional response fields
+- New endpoints
+
+## Output Format
+
+For each change provide:
+- `change`
+- `classification`
+- `affected_clients`
+- `mitigation`

package/.github/skills/api-version-migration/references/deprecation-policy.md

@@ -0,0 +1,23 @@
+# Deprecation Policy
+
+## Minimum Policy Elements
+
+- Deprecation notice date
+- Sunset date
+- Supported versions and SLAs
+- Communication channels and cadence
+- Migration docs and examples
+
+## Header Guidance
+
+Use standard deprecation headers where possible:
+- `Deprecation: true`
+- `Sunset: <RFC 1123 date>`
+- `Link: <migration doc>`
+
+## Communication Cadence
+
+- T0: announce deprecation with migration docs
+- T0 + 30d: first reminder and client usage report
+- T0 + 60d: escalation to lagging clients
+- T0 + 90d+: sunset execution

package/.github/skills/api-version-migration/references/migration-strategies.md

@@ -0,0 +1,25 @@
+# Migration Strategies
+
+## Strategy Options
+
+- `parallel versions`: run v1 and v2 concurrently with deprecation window.
+- `compatibility shim`: expose v2 backend with v1 compatibility adapter.
+- `big-bang cutover`: only for tightly controlled internal clients.
+
+## Preferred Default
+
+Use parallel versions unless there is strong evidence all clients can move at once.
+
+## Rollout Stages
+
+1. Internal validation
+2. Early adopter clients
+3. Broad rollout with deprecation notices
+4. Sunset and removal
+
+## Rollback Conditions
+
+Define objective rollback triggers:
+- error rate spike
+- key client failures
+- data integrity regression

package/.github/skills/api-version-migration/scripts/assertion_runner.py

@@ -0,0 +1,27 @@
+import sys
+from pathlib import Path
+
+
+COMMON_SCRIPTS = Path(__file__).resolve().parents[2] / "common" / "scripts"
+if str(COMMON_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(COMMON_SCRIPTS))
+
+from assertion_core import run_cli
+
+
+def _rule_map() -> dict[str, list[str]]:
+    return {
+        "phased_rollout_present": [r"phase", r"rollout", r"parallel"],
+        "deprecation_timeline_included": [r"deprecation", r"sunset", r"timeline"],
+        "client_compatibility_matrix": [r"compatibility matrix", r"client"],
+        "breaking_change_detection": [r"breaking", r"non-breaking", r"classification"],
+        "mitigation_per_change": [r"mitigation", r"shim", r"adapter"],
+        "affected_clients_considered": [r"affected client", r"consumer", r"client group"],
+        "objective_rollback_triggers": [r"rollback", r"threshold", r"trigger"],
+        "monitoring_signals_defined": [r"error rate", r"latency", r"monitor"],
+        "operational_ownership_defined": [r"owner", r"ownership", r"responsibility"],
+    }
+
+
+if __name__ == "__main__":
+    run_cli("Run API migration assertions against output text.", _rule_map)

package/.github/skills/api-version-migration/templates/client-compatibility-matrix.md

@@ -0,0 +1,4 @@
+# Client Compatibility Matrix
+
+| Client | Current Version | Target Version | Blocking Changes | Adapter Needed | Owner | Deadline |
+|---|---|---|---|---|---|---|

package/.github/skills/api-version-migration/templates/migration-plan-template.md

@@ -0,0 +1,26 @@
+# API Version Migration Plan
+
+## Objective
+
+## Current State
+
+## Target State
+
+## Change Classification
+
+| Change | Classification | Affected Clients | Mitigation |
+|---|---|---|---|
+
+## Migration Strategy
+
+## Rollout Phases
+
+## Rollback Criteria
+
+## Deprecation Timeline
+
+## Testing Plan
+
+## Monitoring and Alerts
+
+## Risks and Dependencies

package/.github/skills/architecture-blueprint-generator/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: architecture-blueprint-generator
+description: >
+  Create a codebase-grounded architecture blueprint for an existing software system.
+  Use this whenever the user asks to document architecture, generate an architecture
+  blueprint, explain system structure, produce C4 or component diagrams, capture
+  architecture decision records, or create an implementation guide for extending a
+  codebase. Use it for architecture-focused repo analysis even when the user does not
+  say "blueprint" explicitly. Do not use it for narrow bug fixes or for broad seven-doc
+  codebase onboarding when acquire-codebase-knowledge is the better fit.
+license: MIT
+compatibility: 'Cross-platform. Works best with repository file access, search, and optional Mermaid validation tools.'
+metadata:
+  version: "1.0"
+argument-hint: 'Optional: repo or folder scope, preferred diagram type, detail level, target audience, or whether to include ADRs and extension guidance'
+---
+
+# Architecture Blueprint Generator
+
+Use this skill when the user wants one architecture-centered deliverable that explains how a system is structured today and how future work should fit into it.
+
+## Trigger Cues
+
+Use this skill for prompts like:
+- "document this architecture"
+- "create an architecture blueprint for this repo"
+- "map the system design and integration points"
+- "generate C4 diagrams from the codebase"
+- "explain the architectural layers and patterns"
+- "create a technical blueprint for future development"
+- "summarize architecture decisions and extension points"
+
+Prefer [../acquire-codebase-knowledge/SKILL.md](../acquire-codebase-knowledge/SKILL.md) when the user explicitly wants full-project onboarding across multiple documents rather than a single architecture artifact.
+
+## Output Contract
+
+Default output is a single `Project_Architecture_Blueprint.md` document unless the user asks for another filename or format.
+
+Before finishing, confirm that the blueprint:
+
+1. Is grounded in code, configuration, or verifiable repo artifacts rather than theory.
+2. Separates confirmed facts from hypotheses, gaps, and risks.
+3. Explains component boundaries, dependency flow, data flow, and cross-cutting concerns.
+4. Includes extension guidance for new development.
+5. Includes evidence references to concrete files, configs, or commands used.
+6. Uses diagrams only when they clarify the architecture and they match observed implementation.
+
+## First Response
+
+Lock these inputs before drafting. If the user already supplied them, do not ask again.
+
+1. Scope: whole repo, subsystem, or service.
+2. Audience: engineers, architects, delivery team, executives, or mixed.
+3. Desired depth: high-level, detailed, or implementation-ready.
+4. Diagram preference: C4, component, flow, UML, Mermaid, or none.
+5. Whether to include ADRs, code examples, and extension patterns.
+
+## Working Modes
+
+| User need | Mode | Primary output |
+|---|---|---|
+| Understand an existing system quickly | Blueprint | One architecture blueprint document |
+| Explain one service or bounded area | Focused Slice | Narrow blueprint scoped to one subsystem |
+| Prepare for implementation | Build Guide | Blueprint plus extension and implementation guidance |
+| Capture significant decisions | ADR Companion | Blueprint plus ADR appendix or separate ADRs |
+
+## Operating Workflow
+
+1. Read [references/workflow.md](./references/workflow.md) for the end-to-end flow.
+2. Use [references/analysis-checkpoints.md](./references/analysis-checkpoints.md) to inspect architecture evidence before drafting claims.
+3. Use [references/technology-patterns.md](./references/technology-patterns.md) only for detected stacks instead of loading everything by default.
+4. Use [references/diagram-guidance.md](./references/diagram-guidance.md) before generating diagrams.
+5. Use [references/decision-records.md](./references/decision-records.md) when the user wants ADRs or when decisions are architecturally significant.
+6. Start from the template in [templates/project-architecture-blueprint-template.md](./templates/project-architecture-blueprint-template.md).
+7. If ADRs are needed, use [templates/adr-template.md](./templates/adr-template.md).
+8. If you need style calibration, use the examples in [examples/blueprint-outline-example.md](./examples/blueprint-outline-example.md) and [examples/finding-style-example.md](./examples/finding-style-example.md).
+
+## Diagram Rules
+
+- Prefer C4 for software systems, containers, and components.
+- Prefer flow or sequence-style diagrams for runtime behavior or request paths.
+- Prefer component or dependency diagrams when showing layer boundaries.
+- Do not fabricate relationships that are not evidenced in the codebase.
+- If Mermaid is used, validate the diagram before presenting it.
+
+## Output Rules
+
+- Lead with the architectural approach actually implemented, not the idealized pattern name.
+- Distinguish observed architecture from intended architecture when the repo shows drift.
+- Mark missing evidence as `Unknown` or `Needs verification` instead of guessing.
+- Keep code examples short and architectural; do not dump large files.
+- Include a short section on risks, architectural debt, and likely extension pitfalls.
+
+## Validation Checklist
+
+Before finishing, confirm that:
+
+1. Every major architectural claim has evidence.
+2. The diagrams and narrative agree with each other.
+3. Cross-cutting concerns are covered only when evidence exists.
+4. The blueprint contains concrete extension guidance, not just description.
+5. Risks, assumptions, and unknowns are explicit.
+
+## Bundled Assets
+
+| File | Use when |
+|---|---|
+| [references/workflow.md](./references/workflow.md) | Always. Core workflow and deliverable shaping. |
+| [references/analysis-checkpoints.md](./references/analysis-checkpoints.md) | Always. Evidence collection and section-by-section questions. |
+| [references/diagram-guidance.md](./references/diagram-guidance.md) | Before generating C4, component, or flow diagrams. |
+| [references/decision-records.md](./references/decision-records.md) | When ADRs or rationale capture are requested. |
+| [references/technology-patterns.md](./references/technology-patterns.md) | When stack-specific analysis is needed. |
+| [templates/project-architecture-blueprint-template.md](./templates/project-architecture-blueprint-template.md) | Starting structure for the blueprint. |
+| [templates/adr-template.md](./templates/adr-template.md) | ADR appendix or standalone ADRs. |
+| [examples/blueprint-outline-example.md](./examples/blueprint-outline-example.md) | Example architecture blueprint skeleton. |
+| [examples/finding-style-example.md](./examples/finding-style-example.md) | Example evidence-backed findings and risks. |
+| [evals/evals.json](./evals/evals.json) | Starter regression prompts for improving this skill. |
+
+## Regression Evals
+
+Starter eval prompts live in [evals/evals.json](./evals/evals.json). Use them when iterating on the skill.

package/.github/skills/architecture-blueprint-generator/evals/evals.json

@@ -0,0 +1,42 @@
+{
+  "skill_name": "architecture-blueprint-generator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Create a Project_Architecture_Blueprint.md for this repository. Focus on the actual architectural pattern, key boundaries, integration points, deployment shape, and guidance for where new features should go. Include diagrams only if they are supported by evidence from the repo.",
+      "expected_output": "A single architecture blueprint grounded in repository evidence, with explicit boundary analysis, risks, and extension guidance.",
+      "files": [],
+      "expectations": [
+        "The output distinguishes observed architecture from inferred or unknown areas.",
+        "The output includes component boundaries, dependency flow, and integration points.",
+        "The output includes extension guidance for future development.",
+        "The output includes evidence references to specific repository artifacts.",
+        "Any diagrams included are justified by observed implementation rather than generic architecture theory."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Analyze only the copilot-observability folder and produce an implementation-ready architecture blueprint for the delivery team. I need runtime components, data flow, cross-cutting concerns, likely architectural risks, and an ADR appendix for the most significant decisions you can substantiate from the code and config.",
+      "expected_output": "A scoped blueprint for one subsystem with implementation-ready detail and evidence-backed ADR candidates.",
+      "files": [],
+      "expectations": [
+        "The output respects the requested scope and does not drift into unrelated folders.",
+        "The output includes runtime components and a concrete data or request flow.",
+        "The output includes risks and ADRs that are either evidenced or clearly marked as inferred.",
+        "The output provides guidance that a delivery team could use to add or modify features safely."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Document this repo's architecture for a mixed audience of engineers and architects. Use C4-style thinking where appropriate, but if the repo does not support a full C4 stack, say so and fall back to the smallest accurate set of diagrams. Call out any mismatch between the architecture the repo claims to use and the one the code actually shows.",
+      "expected_output": "A blueprint that uses the right level of abstraction, avoids speculative diagrams, and highlights architecture drift when present.",
+      "files": [],
+      "expectations": [
+        "The output chooses diagram levels based on available evidence rather than forcing a full C4 hierarchy.",
+        "The output calls out architecture drift or alignment between stated and implemented patterns.",
+        "The output stays architecture-focused and does not turn into a generic repo inventory.",
+        "The output remains suitable for both engineers and architects."
+      ]
+    }
+  ]
+}

package/.github/skills/architecture-blueprint-generator/examples/blueprint-outline-example.md

@@ -0,0 +1,25 @@
+# Example Blueprint Outline
+
+This is a shortened example that shows the tone and level of specificity expected from the final blueprint.
+
+## Executive Summary
+The platform is implemented as a modular monolith with clear inbound API, application orchestration, and infrastructure adapter layers. The repo naming suggests clean architecture, but the actual enforcement is partial because several application services import persistence concerns directly.
+
+## Architectural Overview
+- Primary pattern: layered modular monolith
+- Supporting pattern: background job processing for asynchronous work
+- Key boundary: HTTP controllers route into application services, which coordinate domain logic and integrations
+- Drift: repository interfaces exist, but some features bypass them for direct ORM access
+
+## Component Model
+| Component | Responsibility | Depends on | Evidence |
+|---|---|---|---|
+| API layer | Receives HTTP requests and serializes responses | Application services | route definitions, controller classes |
+| Application layer | Coordinates use cases and transaction flow | Domain models, repository contracts, integration clients | service modules, dependency injection wiring |
+| Infrastructure layer | Database access, queues, external APIs | Frameworks and SDKs | ORM config, repository implementations, client adapters |
+
+## Risk Example
+The architecture relies on informal layering conventions rather than automated dependency rules. This increases the chance that future features will place integration logic in controllers or domain modules.
+
+## Extension Guidance Example
+New integrations should enter through infrastructure adapters with application-level interfaces. Avoid calling third-party SDKs from controllers or domain entities because that would tighten framework coupling and reduce testability.

package/.github/skills/architecture-blueprint-generator/examples/finding-style-example.md

@@ -0,0 +1,29 @@
+# Finding Style Examples
+
+Use concise, evidence-backed findings.
+
+## Strong finding
+
+The service uses a container-style boundary between web API, worker, and database concerns because the deployment config defines separate runtime units and the source tree mirrors that split. Evidence: application bootstrap files, worker entrypoint, and container or deployment manifests.
+
+Why this is good:
+- states the conclusion plainly
+- explains why the conclusion was reached
+- points to concrete evidence types
+
+## Weak finding
+
+The application seems to follow microservices and probably uses event-driven design.
+
+Why this is weak:
+- speculative
+- mixes two patterns without evidence
+- does not identify where the boundaries actually exist
+
+## Strong risk statement
+
+Configuration is spread across environment files, runtime code, and CI variables, which raises drift risk between environments and makes operational troubleshooting harder.
+
+## Strong extension rule
+
+Add new business workflows in the application layer and keep transport concerns in controllers or handlers. If a new feature requires a third-party service, introduce an adapter in infrastructure and depend on an interface from the application layer.

package/.github/skills/architecture-blueprint-generator/references/analysis-checkpoints.md

@@ -0,0 +1,61 @@
+# Analysis Checkpoints
+
+Use these prompts while analyzing the repo. Answer only what the codebase supports.
+
+## Architecture Overview
+
+- What are the executable or deployable units?
+- What are the main architectural boundaries?
+- Is the dominant pattern layered, modular, hexagonal, event-driven, serverless, or hybrid?
+- What evidence supports that conclusion?
+
+## Component Boundaries
+
+- Which directories or modules act as presentation, application, domain, data, infrastructure, or integration layers?
+- Where do interfaces or contracts exist?
+- Are boundaries enforced through imports, abstractions, or package structure?
+- Where are the violations or shortcuts?
+
+## Dependency Flow
+
+- Which modules depend on which others?
+- Do dependencies point inward toward abstractions or outward toward frameworks?
+- Are there circular or suspicious dependencies?
+- What files best demonstrate the dependency rules?
+
+## Data Architecture
+
+- What core domain entities, DTOs, schemas, or models exist?
+- Where is persistence handled?
+- Where do mapping and transformation happen?
+- What caches, queues, or event stores are visible?
+
+## Runtime and Communication
+
+- How do requests enter the system?
+- What communication is synchronous versus asynchronous?
+- What APIs, messages, or jobs connect components?
+- Where is orchestration handled?
+
+## Cross-Cutting Concerns
+
+- Where are authentication and authorization enforced?
+- How are configuration and secrets supplied?
+- How are logging, tracing, or metrics captured?
+- Where does validation occur?
+- How are failures retried, surfaced, or degraded?
+
+## Testing and Governance
+
+- Do tests mirror the architectural layers?
+- Are there architecture rules in linting, build scripts, or CI?
+- Are ADRs, RFCs, or design docs present?
+- Is there evidence of architecture drift or missing documentation?
+
+## Extension Guidance
+
+- Where should a new domain capability be added?
+- Where should adapters for external systems live?
+- What conventions must be preserved?
+- What dependency rules must not be broken?
+- What are the most likely mistakes a new contributor would make?

package/.github/skills/architecture-blueprint-generator/references/decision-records.md

@@ -0,0 +1,41 @@
+# Decision Records
+
+Use ADRs when the user wants rationale, tradeoffs, and lasting architecture guidance rather than a descriptive snapshot alone.
+
+## When to include ADRs
+
+Include ADRs when the codebase shows or the user requests decisions around:
+- service boundaries
+- data storage choices
+- eventing versus synchronous APIs
+- framework or platform choices
+- security or tenancy models
+- observability and governance patterns
+- migration strategies
+
+## What an ADR should capture
+
+Each ADR should document:
+- title
+- status
+- date
+- context
+- decision
+- alternatives considered
+- consequences and tradeoffs
+- evidence from the codebase or requirements
+
+## How to derive ADRs from code
+
+Infer candidate decisions only when there is clear evidence such as:
+- multiple implementations narrowed to one approach
+- framework conventions that imply a deliberate architectural choice
+- deployment or integration patterns with obvious tradeoffs
+- existing comments, docs, or issue references
+
+Do not invent backstory. If the reason is not visible, state that the decision is inferred from implementation and that rationale should be validated with the team.
+
+## Good usage pattern
+
+Use the blueprint for the "what" and "how".
+Use ADRs for the "why", rejected alternatives, and future implications.