This skill should be used when the user asks to "update an architecture spec", "revise the arch spec", "update this architecture document", "add a new ADR", "change the component boundaries", "fill in the TODOs in the arch spec", "correct the architecture spec", or wants to apply new decisions, corrections, or intentional deviations to an existing architecture technical specification document.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pragmatic-devx-plugin:pragmatic-arch-spec-updateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Update an existing architecture technical specification with new architectural decisions, corrections, or intentional deviations.
Update an existing architecture technical specification with new architectural decisions, corrections, or intentional deviations.
Evolve an arch spec safely — preserving existing ADRs, versioning changes, and appending a changelog. Never overwrite prior decisions; mark superseded ADRs as deprecated rather than deleting them. This skill is the natural next step when pragmatic-arch-spec-check identifies a violation that is resolved via Option B (the code reflects an intentional evolution the spec has not yet captured).
Use this skill when an arch spec already exists and needs to capture new decisions, corrections, or intentional deviations — including when pragmatic-arch-spec-check produces a violation resolved via Option B (the code reflects an intentional evolution the spec hasn't captured yet).
Do not use when:
pragmatic-arch-spec-createpragmatic-arch-spec-validateKey distinction from pragmatic-arch-spec-check: pragmatic-arch-spec-check is read-only diagnosis. This skill is the write operation triggered by its findings (Option B) or by any new architectural decision that must be formally recorded.
pragmatic-arch-spec-create → pragmatic-arch-spec-validate → pragmatic-arch-spec-check → [pragmatic-arch-spec-update] → pragmatic-arch-spec-check
Use this skill when the arch spec needs to catch up with the implemented code, or when a new architectural decision must be formally recorded.
Infer the output language from the existing arch spec:
Language: metadata field, use itAskUserQuestion:In which language would you like the arch spec updates to be written?
1. pt-BR — Portuguese (Brazil)
2. es-ES — Spanish (Spain)
3. en-US — English (United States)
4. Other — specify which language
Record the chosen language and apply it consistently to all new or modified content — ADR text, component descriptions, changelog entries, and TODO comments. Existing content that is not being changed should remain in its original language.
Find the architecture spec file from the user's context. Common location: docs/arch/*.arch.md.
Read the full document and understand:
[TODO: ...] items already presentAnalyze what needs to change:
pragmatic-arch-spec-check?Map which sections are directly affected and which may be indirectly impacted — a change to a component boundary may also affect dependency direction rules, data flow descriptions, and NFRs.
This is a mandatory step. Do not apply any changes until the full scope and intent of the update is clear.
After analyzing the spec and the requested change, use AskUserQuestion to confirm your understanding:
multiSelect rules for this step — always follow these:
multiSelect: true — multiple spec sections may need updatingmultiSelect: true — changes often ripple across multiple sectionsmultiSelect: true — the update may achieve several things at onceBefore I apply any changes, let me confirm my understanding of this update:
**What I understood**
- [Restate the change as you interpreted it — ask the user to confirm or correct]
**Sections in Scope** → multiSelect: true
Which sections of the arch spec are explicitly changing?
- ADRs (new decision, updated rationale, or superseded decision)
- Component Boundaries (responsibilities, public interfaces)
- Dependency Direction (allowed/forbidden dependencies)
- Architecture Patterns (naming conventions, communication style, error strategy)
- Data Flows (new or changed flow)
- External Integrations (new or changed integration)
- NFRs / Constraints (new non-functional requirement or constraint)
- Open Decisions / TODOs (resolving a placeholder)
**Related Sections to Cascade** → multiSelect: true
Are there sections that should also be updated as a consequence?
(e.g., if a component boundary changes → dependency direction rules may also change)
**Motivation**
- What triggered this change? (new decision, intentional deviation found in code, correction, requirement change)
- Does this supersede any existing ADR or architectural decision?
**Expected Outcome** → multiSelect: true
After this update, what should the spec reflect that it doesn't today?
- New ADR captured
- Intentional deviation now documented
- Component boundary corrected
- TODO resolved
- Outdated decision deprecated
- Version/status bumped
Do not proceed to Step 2.6 until:
Apply this step when the update includes a new or updated ADR.
Use AskUserQuestion to ensure the ADR is fully documented:
To document this architectural decision properly, I need a few more details:
**Decision**
- What was decided? (state the choice made, not the options)
**Options Considered**
- What alternatives were evaluated before this decision?
**Rationale**
- Why was this option chosen over the alternatives?
- What constraints, quality attributes, or trade-offs drove this decision?
**Consequences**
- What are the known trade-offs or downsides of this decision?
- What becomes easier or harder as a result?
If any of these are unknown or still being debated, I'll mark them as open items.
Only skip this step if the update contains no new architectural decisions (e.g., pure wording corrections or TODO resolution with already-known content).
When modifying the arch spec:
Status field if appropriate (e.g., Draft → Review → Approved)Version field:
1.0.0 → 1.0.1) for wording corrections, TODO resolution, or minor clarifications1.0.0 → 1.1.0) for new ADRs, updated component boundaries, or new integrations1.0.0 → 2.0.0) for fundamental architecture changes (e.g., new dependency direction, major component restructuring)~~strikethrough~~ and add a note referencing the new decision. Never delete prior ADRs.---
## Changelog
### v<new-version> — <date>
- <summary of changes — e.g., "Added ADR-05: caching strategy", "Updated boundary for PaymentProcessor component">
After applying changes, verify:
[TODO: ...] items that were addressed are now resolvedReport:
[TODO: ...] items still present in the documentNext step: run pragmatic-arch-spec-check to verify the updated spec now correctly reflects the implemented code.
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub rvfvazquez/pragmatic-devx-plugin --plugin pragmatic-devx-plugin