edercnj/x-update-architecture

Skill: Architecture Document Updater

Purpose

Incrementally updates an architecture document from project artifacts, in two scopes that share one invariant — never regenerative (RULE-008: existing content is only inserted or appended, never removed or rewritten):

• --scope service (default) — updates the service architecture doc (steering/service-architecture.md) from a per-story architecture plan.
• --scope system — updates the system architecture doc (docs/architecture/system.md) after a feature completes, via <!-- AUTO-FILL --> markers (Sections 1-10) + a Decision Log append with ## ID: marker dedup (§11).

Triggers

• /x-update-architecture <STORY-ID> — update the service doc from the story's architecture plan (default scope).
• /x-update-architecture <architecture-plan-path> — update the service doc from a specific plan file.
• /x-update-architecture <FEATURE-ID> --scope system — update the system doc from the feature's artifacts.
• /x-update-architecture <FEATURE-ID> --scope system --dry-run — preview the system-doc diff without writing.
• Service scope runs during Phase 3 (Documentation) of x-implement-story; system scope runs after the final feature PR (x-close-feature) merges.
• SKIP (service) when no architecture plan exists for the feature.

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | <input> | String | Yes | — | Service scope: STORY-ID or architecture-plan-path. System scope: FEATURE-ID (4-digit, e.g. 0099; feature- prefix accepted). | | --scope | Enum | No | service | service → steering/service-architecture.md; system → docs/architecture/system.md. | | --system-md-path | String | No | docs/architecture/system.md | (system scope) Override path to the system architecture doc. | | --dry-run | Boolean | No | false | (system scope) Print the diff without writing. |

Workflow Overview

Dispatch on --scope. Full step-by-step procedures live in references/full-protocol.md.

--scope service (references/full-protocol.md §Scope service):

1. Read the architecture plan + current steering/service-architecture.md (create from _TEMPLATE-SERVICE-ARCHITECTURE.md if absent).
2. Diff plan vs doc; insert/append per section (RULE-008); append a Change History row (§10).
3. Executed by a single general-purpose Documentation Engineer subagent.

--scope system (references/full-protocol.md §Scope system):

1. Validate preconditions (system.md exists; locate .aikittools/features/feature-<ID>-*/).
2. Extract architectural decisions (ADR refs, new components/integrations) from the feature md.
3. Append a Decision Log entry to §11 via Edit, deduped by the ## ID: feature-<ID> marker.
4. Surgically insert new blocks after <!-- AUTO-FILL: <key> --> markers in Sections 1-10, guarded by SHA-256 content-hash checks.
5. --dry-run prints the diff and exits without writing.

Both scopes are idempotent: re-running with the same input yields a byte-identical document.

Error Handling

| Scope | Scenario | Action | |-------|----------|--------| | service | Architecture plan not found | Skip with log: "No architecture plan found; skipping architecture doc update" | | service | Service architecture doc not found | Create from template (Document Creation from Scratch) | | service | Template not found | Use inline fallback structure, log warning | | service | Section heading mismatch | Match by numeric prefix, warn if heading text differs | | service | Merge conflict in Mermaid diagram | Preserve both versions, add comment marking conflict | | system | SYSTEM_MD_MISSING | docs/architecture/system.md (or --system-md-path) not found → abort | | system | FEATURE_DIR_MISSING | .aikittools/features/feature-<ID>-*/ not found → abort | | system | No architectural decisions detected | INFO log; exit 0 without modifying system.md |

Integration Notes

| Skill | Relationship | Context | |-------|-------------|---------| | x-implement-story | called-by | Service scope invoked during Phase 3 (Documentation). | | x-close-feature | called-by | System scope invoked after the final feature PR merges. | | x-generate-docs | called-by | May invoke the system scope as one of its doc targets. | | x-validate-docs | peer | Freshness gate that references the system architecture doc. | | x-internal-plan-arch-story | reads | Generates the input architecture plans consumed by the service scope. | | x-generate-adr | calls | Service scope may trigger ADR generation for new architectural decisions. |

Notes: Rule 45 (CI-Watch) not applicable — this skill does not create PRs. _TEMPLATE-ARCHITECTURE-SYSTEM.md should carry <!-- AUTO-FILL: <key> --> markers at the appropriate section locations to enable the system-scope surgical inserts.

Knowledge Pack References

| Pack | Files | Purpose | |------|-------|---------| | architecture | patterns/backend/software-architecture/hexagonal/patterns.md | Architecture principles and patterns |