risk

Files (1)

• SKILL.md

SKILL.md (first lines)

# Risk Skill

## Purpose

Help identify, structure, and update architecture risks for review and
prioritization. Treat every AI-created risk, relation, assessment, mitigation,
and impact claim as proposed until a human reviewer accepts it in the
repository.

This skill is guidance and reusable content only. Do not implement AI execution,
do not implement a generator, and do not add automation as part of using this
skill.

Apply the repository contract hierarchy: this skill narrows `AGENTS.md`, and
`AGENTS.md` adapts `general-semantic-contracts.md`. Do not duplicate general
metadata, anchor, Docs-as-Code, arc42, or traceability rules here unless the risk
workflow needs a stricter rule.

## Core Workflow

1. Inspect existing architecture documentation before writing.
2. Inspect relevant source code, configuration, deployment files, incidents,
   tests, ADRs, quality scenarios, and operational evidence when available.
3. Identify existing risks, ADRs, quality scenarios, requirements, constraints,
   components, interfaces, controls, and concepts that may relate to the risk.
4. Check whether an existing risk already covers the concern.
5. Draft a proposed risk only when the concern is not covered by an existing
   artifact.
6. Write the risk statement as cause, event, and impact.
7. Assess likelihood, impact, priority, timeframe, and confidence qualitatively.
8. Propose actionable mitigations, monitoring, or review actions with an owner
   where evidence supports them.
9. Propose explicit metadata relations to decisions, quality scenarios,
   requirements, affected architecture documents, mitigations, and evidence.
10. Update affected artifacts with **outgoing** relations only when justified by evidence.
    Never create reciprocal incoming relations; they are derived automatically during generation.
11. Add stable AsciiDoc anchors to created documentation artifacts and use
    anchor-based `xref` links for visible references to documentation artifacts.
12. Prefer small, reviewable patches.
13. Run the repository validator after changes if one is available.

## Required Reading

Read these references as needed:

- `../../src/docs/arc42/04-solution-strategy/doc-04001-metamodel.adoc` before writing or
  changing artifact metadata, artifact types, lifecycle states, or relation
  semantics.
- `../references/metadata-rules.md` before writing YAML front matter.
- `../references/relation-rules.md` before proposing or updating relations.
- `../references/risk-writing-guide.md` before creating or changing risks.
- `../references/adr-writing-guide.md` before linking risks to ADRs.
- `../references/quality-scenario-guide.md` before linking risks to quality
  scenarios.

Use these templates:

- `../../templates/risk.adoc` for new risk artifacts.
- `../../templates/impact-report.adoc` for review reports when the user wants
  analysis without direct artifact changes.

## Inputs To Collect

- Architecture context, affected outcome, and risk owner.
- Decision, component, interface, constraint, quality scenario, control, or
  requirement that creates or exposes the risk.
- Known incidents, assumptions, dependencies, threat findings, operational
  constraints, or uncertainties.
- Existing risk IDs and related artifact IDs where available.
- Evidence for likelihood, impact, confidence, mitigation, or monitoring.
- Review scope: draft-only, update artifacts, or produce an impact report.

## Inspection Rules

- Prefer reviewed repository source files over conversational memory.
- Do not load derived output as evidence or architecture context. This includes
  `generated/`, `build/`, `dist/`, `target/`, `out/`, rendered HTML/PDF,
  generated indexes, traceability views, and assembled documentation.
- Treat explicit metadata as more authoritative than inferred prose.
- Check existing risk IDs before assigning new IDs.
- Read the closest architecture index, risk list, ADR register, quality
  scenario list, threat model, concept chapter, and affected arc42 chapter when
  present.
- Inspect code only to gather evidence, discover affected components, or verify
  controls; do not implement mitigations unless the user separately asks for
  implementation.
- Separate risks from issues, decisions, constraints, defects, and open
  questions.

## Output Rules

- Keep all AI-generated artifacts `status: proposed` or `status: draft`.
- Set `reviewed: false` for AI-generated or AI-modified content unless human
  review is already recorded in the repository.
- Preserve existing accepted statuses unless there is explicit repository
  evidence that they changed.
- Do not mark a risk accepted unless human acceptance is already recorded.
- Do not retire a risk on your own judgement. When the risk no longer exists,
  propose `validity: retired` with `retired_on`, a `retired_reason`, and a
  `retired_note`, and leave the decision to the risk owner. A residual risk the
  team knowingly carries stays active; its acceptance belongs in the risk
  artifact, not on the validity axis.
- Never delete a risk that stopped applying, and never change the status of a
  relation that points at it. The relation stays valid history and the
  generator marks it inactive.
- Avoid false precision in likelihood, impact, priority, or confidence.
- Mark uncertainty explicitly instead of pretending evidence is complete.
- Prefer actionable mitigations with owners.
- Do not create new risk artifacts when a justified relation to an existing
  artifact is sufficient.
- Keep metadata relation targets as stable artifact IDs; render visible
  documentation references as anchor-based AsciiDoc `xref` links.
- Keep risk impact and traceability data exclusively in YAML front matter
  relations. Do not add a manual impact matrix, manual traceability matrix, or
  reciprocal incoming relations to the risk body.
- Make impact and traceability visible through `=== Impact` and
  `=== Traceability` sections that include the generated local
  `generated/<artifact-anchor>-impact.adoc` and
  `generated/<artifact-anchor>-traceability.adoc` fragments with

From docs-as-code-toolkit/architecture-knowledge-toolkit, MIT.

More from docs-as-code-toolkit/architecture-knowledge-toolkit