Pragmatic arch spec update

pragmatic-arch-spec-update

Update an existing architecture technical specification with new architectural decisions, corrections, or intentional deviations.

Purpose

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).

When This Skill Applies

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:

• No arch spec exists yet → use pragmatic-arch-spec-create
• The user only wants a quality review of the spec document without making changes → use pragmatic-arch-spec-validate

Key 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.

Lifecycle Position

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.

How to Update an Architecture Spec

Step 0 — Language Detection

Infer the output language from the existing arch spec:

1. If the spec contains a Language: metadata field, use it
2. Otherwise, infer from the majority language of prose content in ADR rationale and component descriptions — if ≥80% of prose words are attributable to a single language, use that language
3. If no prose exists or no language reaches 80%, use AskUserQuestion:

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.

Step 1 — Locate the Arch Spec

Find the architecture spec file from the user's context. Common location: docs/arch/*.arch.md.

Read the full document and understand:

• Current status and version
• Existing ADRs and their decisions
• Component boundaries and dependency rules
• Any [TODO: ...] items already present

Step 2 — Understand the Change

Analyze what needs to change:

• Is this a new ADR (a decision not previously documented)?
• Is this an update to component boundaries (responsibilities, public interfaces, dependency direction)?
• Is this a correction to existing content (wrong information, outdated constraint)?
• Is this resolving a [TODO: ...] placeholder?
• Is this capturing an intentional deviation identified by 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.

Step 2.5 — Confirm Scope and Intent Before Proceeding

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:

• Sections in scope: multiSelect: true — multiple spec sections may need updating
• Related sections to cascade: multiSelect: true — changes often ripple across multiple sections
• Expected outcomes: multiSelect: true — the update may achieve several things at once

Before 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:

• The exact sections in scope are confirmed
• The motivation is understood
• Whether any existing ADR is superseded is clear

Step 2.6 — Capture ADR Details for New Decisions

Apply this step when the update includes a new or updated ADR.

Use AskUserQuestion to ensure the ADR is fully documented. Every question here must carry a recommended answer (➡️), derived in this priority order: (1) constraints or quality attributes already recorded elsewhere in this spec, (2) patterns evident in the codebase, (3) a pragmatic default stated as such.

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?
  ➡️ Draft from the spec's existing constraints — e.g. if section 3 already rules out vendor lock-in, list that as a rejected option

**Rationale**
- Why was this option chosen over the alternatives?
- What constraints, quality attributes, or trade-offs drove this decision?
  ➡️ Point at the specific NFR or constraint already documented in this spec that this decision satisfies

**Consequences**
- What are the known trade-offs or downsides of this decision?
- What becomes easier or harder as a result?
  ➡️ No strong signal — recommend stating at least one concrete trade-off rather than leaving it blank

If any of these are unknown or still being debated, say so — or just confirm the ➡️ recommendation. I'll mark anything left open as an open item.

Only skip this step if the update contains no new architectural decisions (e.g., pure wording corrections or TODO resolution with already-known content).

Step 2.65 — Follow-up Round for Dependent Decisions

After Step 2.6, check whether the new/updated ADR unlocks a dependent decision that could not have been asked before it (its options only make sense given the ADR just captured). Common triggers:

Parent answer	Dependent question to ask now
New component boundary	Does the dependency direction table (6.2) need a new row?
New external integration	Which protocol/contract? Retry and failure-handling strategy?
ADR introduces async communication	Which broker? At-least-once or exactly-once delivery expected?
ADR changes an NFR target (e.g. availability)	Does this require a new failover or redundancy decision?

If any dependent question applies, ask it now via AskUserQuestion — with a recommended answer, following the same rule as Step 2.6 — instead of leaving it implicit or as a fresh [TODO: ...]. Only questions whose parent decision itself remained undecided should still become TODOs.

Run this check once. A second round should not itself spawn a third round unless the change is unusually broad — if it does, proceed to Step 3 anyway and leave the remainder as TODOs rather than turning the confirmation into an unbounded loop.

Step 2.7 — Final Consistency Check

Before applying any changes, check whether what was confirmed in Steps 2.5, 2.6, and 2.65 contradicts anything in the existing arch spec content that is not being changed (read in Step 1) — component boundaries, dependency direction, or NFRs that weren't part of this update's scope. Scan for contradiction only, not completeness — that is pragmatic-arch-spec-validate's job.

Known contradiction shapes to check for:

New/changed decision	Existing untouched content	Contradiction pattern
New or updated ADR	Existing dependency direction rules (6.2)	The new decision implies a dependency the existing rules forbid
New component boundary	Existing component diagram (4.1) not marked in scope	A component referenced elsewhere in the spec now has an inconsistent responsibility
New NFR target	Existing constraint elsewhere in the spec	The new target conflicts with a constraint the update didn't touch

If no contradiction is found, skip straight to the recap below.

If a contradiction is found, do not silently resolve it. Present it explicitly and wait:

⚠️ Possible contradiction: this update says "...", but the existing spec (section X, untouched) says "...". Which should hold — or should section X also be updated as part of this change?

Once clear, present a short recap and require explicit confirmation before writing:

Here's what I'm about to change: [sections in scope, one line each]. Everything else in the spec stays as-is. Confirm before I apply this?

STOP. Do not proceed to Step 3 until the user explicitly confirms.

Step 3 — Apply the Changes

When modifying the arch spec:

1. Preserve all content not being changed
2. Update diagrams when their source sections change — diagrams must always reflect the current state of the spec:
   • Section 4.1 (Component Diagram) → update when any component is added, removed, or renamed
   • Section 6.2 (Dependency Direction) → update when dependency rules change
   • Section 7 (Data Flow) → update when any flow step, participant, or async boundary changes
   • If a diagram becomes inaccurate due to the change, it must be updated in the same edit — never leave a diagram describing a state the spec has moved away from
3. Update the Status field if appropriate (e.g., Draft → Review → Approved)
4. Increment the Version field:
   • Patch bump (1.0.0 → 1.0.1) for wording corrections, TODO resolution, or minor clarifications
   • Minor bump (1.0.0 → 1.1.0) for new ADRs, updated component boundaries, or new integrations
   • Major bump (1.0.0 → 2.0.0) for fundamental architecture changes (e.g., new dependency direction, major component restructuring)
5. Deprecate superseded ADRs — mark them with ~~strikethrough~~ and add a note referencing the new decision. Never delete prior ADRs.
6. Append a changelog entry at the end of the document:

---
## Changelog

### v<new-version> — <date>
- <summary of changes — e.g., "Added ADR-05: caching strategy", "Updated boundary for PaymentProcessor component">

Step 4 — Validate Consistency After Update

After applying changes, verify:

• All [TODO: ...] items that were addressed are now resolved
• ADR references within the document are consistent (no orphan references)
• Component names used in dependency rules match the updated component boundaries table
• Dependency direction rules are consistent with the updated component structure
• No section is left contradicting the changes applied

Step 5 — Output Summary and Next Steps

Report:

1. A concise summary of what was changed
2. Any remaining [TODO: ...] items still present in the document
3. Sections that may need human review due to the changes

Arch spec updated — docs/arch/<name>.arch.md.

Next step: Run pragmatic-arch-spec-check to verify the updated spec now correctly reflects the implemented code.