architecture-impact
Analyze and document architecture impact for feature requests, Epic issues, UserStory issues, refactoring tasks, issue implementation, and review tasks. Use when Codex is asked to handle a feature request, decide whether feature work should become an Epic or UserStory, create or refine an Epic, mark a UserStory or refactoring issue, implement feature or refactoring work, review a pull request or review task, assess whether code changes affect architecture documentation, update affected arc42 sections, connect features or refactorings to ADRs, quality goals, quality scenarios, risks, components, runtime scenarios, deployment views, or create follow-up ADRs with diagrams.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 4
- Forks
- 2
01 前言 Front Matter
- name
- architecture-impact
- description
- Analyze and document architecture impact for feature requests, Epic issues, UserStory issues, refactoring tasks, issue implementation, and review tasks. Use when Codex is asked to handle a feature request, decide whether feature work should become an Epic or UserStory, create or refine an Epic, mark a UserStory or refactoring issue, implement feature or refactoring work, review a pull request or review task, assess whether code changes affect architecture documentation, update affected arc42 sections, connect features or refactorings to ADRs, quality goals, quality scenarios, risks, components, runtime scenarios, deployment views, or create follow-up ADRs with diagrams.
03 SKILL.md 正文
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
- 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.
- 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.
- 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.
- 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]. - Start every Epic and UserStory description with the pattern
As a [Role], I want to [Action], so that [Benefit]. - 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.
- 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]. - 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.featurespec 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. - Record the feature or refactoring at every affected place in the
architecture documentation. Prefer a short
Affected FeaturesorAffected Refactoringssection or table with stable issue links, status, and explicitxreflinks to related architecture artifacts. - 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.
- 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.mdto draft a new proposed ADR or update the affected decision trail. - 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.
- 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. - Add or update quality scenarios and risks only when existing artifacts do
not already cover the feature impact. Use
../quality-scenario/SKILL.mdand../risk/SKILL.mdfor those artifacts. - Run the relevant validators, generators, render checks, tests, or manual checks. Report any unavailable verification and remaining open human decisions.
- 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.mdfor architecture documentation, Docs-as-Code, metadata, traceability, quality, risks, backlog management, and review rules.../../AGENTS.mdfor automated-contributor rules.../bdd-specification/SKILL.mdby default for any new or changed observable behaviour, to specify it as Gherkin and bridge it into tests.../adr/SKILL.mdbefore creating or changing ADRs, or when a feature conflicts with an existing decision.../quality-scenario/SKILL.mdbefore creating or changing quality scenarios.../risk/SKILL.mdbefore creating or changing risks.../traceability-review/SKILL.mdbefore changing relation metadata or reviewing traceability.../slice-issues/SKILL.mdwhen the Epic or UserStory needs child issues or reviewable implementation slices.../implement-issue-workflow/SKILL.mdwhen continuing from feature analysis into implementation.../pr-review/SKILL.mdwhen 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]. - Assign a UserStory to an existing matching Epic when one exists. Prefer a real GitHub sub-issue or parent-child relation; use linked issue references only when sub-issues are unavailable.
- Keep child issues small and independently reviewable. Create sub-issues as real sub-issues for Epics and UserStories when the repository allows it.
- Do not create duplicate Epics or UserStories. Search open and recently closed issues before creating a new one.
Refactoring Issue Rules
- Treat refactoring as intentional structural work, not incidental cleanup.
- Prefer a real refactoring issue type, label, or metadata field if the remote repository supports it.
- If no refactoring metadata is available, prefix the issue title with
[REFACTORING]. - Keep refactoring issues separate from behavioral feature changes unless a human explicitly accepts a combined scope.
- Link affected components, ADRs, risks, quality scenarios, tests, and follow-up issues from the refactoring issue.
Documentation Rules
-
Use reviewed repository source files as the source of truth; conversational context and generated prose are advisory until reviewed and committed.
-
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. -
Preserve stable IDs and accepted statuses. Mark AI-created or AI-modified architecture content as draft or proposed unless human acceptance is already recorded.
-
Add feature or refactoring references where the work affects the documentation, not only in a central index. A component affected by a feature or refactoring should name that issue near the component description or in an
Affected FeaturesorAffected Refactoringssection. -
Use explicit AsciiDoc anchors and
xreflinks for visible references. -
Do not manually maintain generated include lists. Regenerate derived include fragments when the repository provides a generator.
-
Keep reusable source content in one reviewed source location and include it elsewhere. Use tagged includes for shared descriptions and diagrams:
// tag::feature-auth-runtime[] [plantuml,feature-auth-runtime,svg] ---- @startuml ' diagram body @enduml ---- // end::feature-auth-runtime[]include::../06-runtime-view/doc-06004-authentication.adoc[tags=feature-auth-runtime]
Review Checklist
- Does the feature, refactoring, or PR change an architecture-significant behavior, boundary, dependency, interface, deployment concern, quality attribute, risk, or operational workflow?
- Is each Epic, UserStory, or refactoring issue marked with the repository's
native metadata, or with
[EPIC],[UserStory], or[REFACTORING]in the issue title when no metadata exists? - Does every Epic and UserStory begin with
As a [Role], I want to [Action], so that [Benefit].? - Is each UserStory assigned to a matching Epic when one exists?
- Does every behaviour-adding or behaviour-changing change have a Gherkin
.featurespecification bridged to tests per../bdd-specification/SKILL.md, or an explicitly recorded human waiver? - Are affected ADRs and quality goals explicitly named?
- Is there a conflict that requires a new or changed ADR?
- Are all affected architecture locations updated with feature references?
- Are new components, runtime scenarios, and deployment changes documented with PlantUML diagrams and short text?
- Are shared diagrams and descriptions included by tag instead of copied?
- Do the Epic and UserStory links cover implementation, documentation, ADRs, risks, quality scenarios, PRs, and real sub-issues where supported?
- Are validators, generators, tests, and render checks run or explicitly noted as not run?
- Does the change carry a Convergence Check result, with every finding given a
disposition and every blocker its kind, per
../convergence-check/SKILL.md?
04 同仓库更多 Skills
traceability-review
Review explicit architecture traceability metadata for gaps, inconsistencies, unsupported claims, stale links, dangling references, and metamodel violations. Use when Codex needs to inspect artifact relations, validate ADR-to-risk or quality-scenario coverage, propose relation updates, or produce an evidence-backed traceability review report.
slice-issues
Slice GitHub parent issues into reviewable real sub-issues. Use when Codex is asked to split, slice, decompose, refine, or plan a GitHub issue into child issues, sub-issues, implementation slices, or reviewable follow-up issues before implementation work begins.
risk
Create proposed architecture risk artifacts and analyze their traceability to ADRs, quality scenarios, requirements, components, controls, and evidence. Use when Codex needs to identify, draft, update, prioritize, or review architecture risks, separate risks from issues and decisions, propose mitigations, or produce a risk impact report without deciding acceptance.
quality-scenario
Create proposed quality scenarios and analyze their traceability to quality objectives, ADRs, risks, requirements, architecture artifacts, and code evidence. Use when Codex needs to draft or update measurable quality scenarios, inspect existing arc42 Chapter 10 quality requirements, derive scenarios from source evidence without inventing targets, propose metadata relations, or produce a quality scenario impact report.
presentation
Create or update docs-as-code presentation material as AsciiDoc reveal.js decks rendered with docs-toolbox. Use when Codex needs to prepare talks, meetup or conference proposals, speaker notes, demo scripts, event-specific artifacts under talks/, or slide decks that must remain repository-native rather than PowerPoint or Google Slides files.
pr-review
Review GitHub pull requests and proposed branch changes for correctness, regressions, missing tests, documentation-contract violations, traceability gaps, and reviewability. Use when an AI assistant is asked to review a PR, review pull request changes, inspect a PR branch before merge, or produce PR review comments.