القائمة
Architecture Decision Record creation and management — loaded by planner and orchestrator when significant technical decisions need to be recorded with context and consequences
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Keep a Changelog methodology — loaded by the ship phase to update CHANGELOG.md with user-facing changes, filtering out internal-only commits
Generator-evaluator separation and review methodology — loaded by review agents to enforce fresh-context review discipline, Conventional Comments format, and gate verdicts
Adversarially review a technical design document with fresh context before the human gate. Dispatches the built-in `general-purpose` subagent (clean context, no shared history with the design-author) against `docs/plans/<id>/design.md` and presents its verdict — APPROVE, REQUEST CHANGES, or COMMENT. Optional, not part of the QRSPI pipeline. Trigger on "review the design doc", "audit design.md", "is this design ready", or `/eng-design-doc-review`.
Git commit discipline methodology — loaded by the ship phase to produce well-formed commits following conventional commits format, the 50/72 rule, and atomic commit principles
Optional PRD methodology — loaded by the questioner agent when a feature request is vague or complex enough to warrant a structured product spec alongside task.md. Produces a PRD artifact that downstream design-author work can ground decisions in.
Technical design document methodology — loaded by the planner agent when producing implementation plans for features that warrant architecture documentation, trade-off analysis, and rollout planning
| name | documenting-decisions |
| description | Architecture Decision Record creation and management — loaded by planner and orchestrator when significant technical decisions need to be recorded with context and consequences |
| user-invocable | false |
Architecture Decision Records (ADRs) capture significant technical decisions with their context, rationale, and consequences. They are the institutional memory that explains WHY the codebase looks the way it does.
Write the prose this skill governs at a seventh-grade reading
level — short sentences, common words, no unexplained jargon. Full
methodology: skills/writing-prose/SKILL.md.
Every ADR follows this structure:
# NNNN. Decision Title
## Status
Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-title.md)
## Context
What is the issue that we're seeing that is motivating this decision or change?
Describe the forces at play — technical constraints, business requirements,
team capabilities, timeline pressure. Be objective: state facts, not opinions.
## Decision
What is the change that we're proposing and/or doing? State the decision in
full sentences, using active voice: "We will..." not "It was decided that..."
## Consequences
What becomes easier or more difficult to do because of this change? List both
positive and negative consequences. Every decision has trade-offs — if you
cannot identify any negative consequences, you have not thought hard enough.
ADRs live in docs/decisions/ with zero-padded sequential numbering:
docs/decisions/
0001-use-typescript-for-plugin.md
0002-agent-per-phase-architecture.md
0003-file-based-state-management.md
To determine the next number, read the existing files in docs/decisions/
and increment the highest number. If the directory is empty or does not exist,
start at 0001.
Write an ADR when the decision:
Chooses between alternatives — You evaluated multiple options and picked one. The rejected alternatives and the reasons for rejection are valuable context for future developers who will wonder "why didn't we just..."
Involves significant trade-offs — The decision sacrifices something (performance, simplicity, flexibility) to gain something else. Record what was traded and why.
Breaks an established convention — Deviating from existing patterns is sometimes correct, but the reasoning must be explicit so the deviation is not "fixed" back by a future developer who assumes it was a mistake.
Introduces a new dependency — Adding a library, service, or tool creates a long-term commitment. Record why this dependency was chosen over alternatives and what the exit strategy is.
Do not write an ADR when:
The choice is obvious — If there is one clearly correct option and no reasonable alternative, an ADR adds bureaucratic overhead without value.
Following established patterns — If the codebase already uses a pattern and you are applying it to a new case, no decision was made.
Minor implementation details — Function naming, variable scoping, loop structure. These are code-level decisions, not architecture-level.
The decision is trivially reversible — If the choice can be changed in minutes with no downstream impact, it does not need formal documentation.
The decision has been written but not yet accepted. It is open for discussion and may be modified.
The decision has been agreed upon and is in effect. The codebase should conform to this decision.
The decision is no longer relevant — the feature or system it pertains to has been removed. The ADR remains for historical context.
A newer decision has replaced this one. The ADR must include a reference to its successor:
## Status
Superseded by [0007](0007-new-approach-to-state.md)
The successor ADR should reference what it supersedes in its Context section to maintain the decision trail.