architecture-impact

Files (1)

• SKILL.md

SKILL.md (first lines)

# Architecture Impact

## Overview

Keep feature work, refactorings, reviews, and architecture knowledge
synchronized. A feature request or refactoring task is not complete until the
relevant implementation, issue tracking, and architecture documentation tell the
same story.

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

This skill intentionally repeats a few backlog and issue-marking rules from
`general-semantic-contracts.md` because they are operationally important while
handling feature and review work. Keep the general contract as the long-term
source of truth when these rules evolve.

## Core Workflow

1. Identify the feature request, Epic issue, UserStory issue, refactoring task,
   implementation issue, pull request, or review task and read its title,
   description, acceptance criteria, comments, linked issues, and linked PRs.
2. Inspect the current architecture documentation before changing code or
   judging a review. Read the affected arc42 chapter files, ADR index, existing
   ADRs, quality goals, quality scenarios, risks, building blocks, runtime
   scenarios, deployment views, and relevant source files.
3. Classify each feature request before creating or updating backlog issues. If
   the request is broad enough to coordinate multiple user stories or slices,
   create or update an Epic. If it is small enough for one reviewable slice,
   create or update a UserStory. If the size is unclear and the decision affects
   issue structure, ask a short clarifying question before creating the issue.
4. Mark Epics and UserStories in the remote project backlog following the type
   and label taxonomy in `../references/issue-labels.md`. Use the repository's
   Epic or UserStory issue type, label, or metadata when available; otherwise
   prefix the issue title with `[EPIC]` or `[UserStory]`.
5. Start every Epic and UserStory description with the pattern
   `As a [Role], I want to [Action], so that [Benefit].`
6. Assign each UserStory to a matching Epic when one exists. Prefer real
   sub-issues or parent-child issue relations when the repository supports them;
   otherwise link the UserStory from the Epic and the Epic from the UserStory.
7. Mark every requested refactoring in the remote project issue. Use the
   repository's refactoring issue type, label, or metadata when available; if no
   dedicated metadata exists, prefix the issue title with `[REFACTORING]`.
8. For any change that adds or changes observable behaviour, specify that
   behaviour with `../bdd-specification/SKILL.md`. This is the strict default and
   covers new features, behavioural enhancements, and behaviour-changing bug
   fixes. Capture the acceptance behaviour as a language-agnostic Gherkin
   `.feature` spec as early as request or analysis time. The specification and
   its scenario-to-test bridge are mandatory at the latest when the change is
   implemented. Relax this only with an explicit human waiver, recorded with its
   rationale in the issue, pull request, or Q&A document. Pure refactorings add
   no behaviour and need no new scenarios, but must keep the existing specs and
   their bridged tests passing.
9. Record the feature or refactoring at every affected place in the
   architecture documentation. Prefer a short `Affected Features` or
   `Affected Refactorings` section or table with stable issue links, status,
   and explicit `xref` links to related architecture artifacts.
10. Explicitly mention affected existing ADRs, quality goals, quality scenarios,
   risks, constraints, components, interfaces, runtime scenarios, and deployment
   elements in the issue, implementation notes, review output, or architecture
   changes.
11. If the feature or refactoring conflicts with an accepted or proposed ADR,
   quality goal, quality scenario, risk treatment, or constraint, stop treating
   the conflict as an implementation detail. Use `../adr/SKILL.md` to draft a
   new proposed ADR or update the affected decision trail.
12. Document new or changed components, runtime scenarios, and deployment
   changes with a matching PlantUML diagram plus a short textual description.
   Use C4-PlantUML for building-block diagrams.
13. Add diagrams to new ADRs when they help readers compare options. If the same
   diagram or description is also included in the official arc42 structure,
   author it once and include it with `include::...[tags=...]` instead of
   copying it.
14. Add or update quality scenarios and risks only when existing artifacts do
   not already cover the feature impact. Use `../quality-scenario/SKILL.md` and
   `../risk/SKILL.md` for those artifacts.
15. Run the relevant validators, generators, render checks, tests, or manual
    checks. Report any unavailable verification and remaining open human
    decisions.
16. Before the work is treated as complete, run `../convergence-check/SKILL.md`.
    Impact analysis establishes what the change touches; the gate asks whether
    the request, the specification, the architecture record, the implementation
    and the delivery metadata still agree afterwards.

## Required Reading

Read these files when the feature or review touches the corresponding scope:

- `../../general-semantic-contracts.md` for architecture documentation,
  Docs-as-Code, metadata, traceability, quality, risks, backlog management, and
  review rules.
- `../../AGENTS.md` for automated-contributor rules.
- `../bdd-specification/SKILL.md` by default for any new or changed observable
  behaviour, to specify it as Gherkin and bridge it into tests.
- `../adr/SKILL.md` before creating or changing ADRs, or when a feature
  conflicts with an existing decision.
- `../quality-scenario/SKILL.md` before creating or changing quality scenarios.
- `../risk/SKILL.md` before creating or changing risks.
- `../traceability-review/SKILL.md` before changing relation metadata or
  reviewing traceability.
- `../slice-issues/SKILL.md` when the Epic or UserStory needs child issues or
  reviewable implementation slices.
- `../implement-issue-workflow/SKILL.md` when continuing from feature analysis
  into implementation.
- `../pr-review/SKILL.md` when the task is a pull request or review task.

## Backlog Issue Rules

- Treat an Epic as the coordination artifact for a feature that is too large for
  one reviewable slice or naturally contains multiple UserStories.
- Treat a UserStory as a reviewable slice of user value that can fit into one
  focused implementation flow.
- Prefer real Epic and UserStory issue types, labels, or metadata if the remote
  repository supports them.
- If no Epic metadata is available, prefix the Epic issue title with `[EPIC]`.
- If no UserStory metadata is available, prefix the UserStory issue title with
  `[UserStory]`.
- Start every Epic and UserStory description with
  `As a [Role], I want to [Action], so that [Benefit].`

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

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