Skip to content

Architecture

Logical ID: kiyo.architecture · Entry: src/kiyo/skills/architecture/SKILL.md · Procedure: workflows/architecture.md (KIYO-ARCH-001)

Purpose

Section titled “Purpose”

Architecture handles several kinds of question:

  • analyzing or reviewing a project or module’s architecture;
  • assessing a proposed change’s impact;
  • comparing implementation with approved design decisions.

It is one Skill for all of these. Analysis, review, impact, and drift are intents, not extra Skills or arguments.

It is read-only:

  • no source, test, config, policy, Memory, ADR, or decisions.md writes;
  • no report files unless separately authorized;
  • no automatic builds or tests, dependency installs, external probes, or Git mutations.

Found drift or an accepted design never authorizes a refactor or migration.

Five output categories

Section titled “Five output categories”

The core of the Skill is keeping these apart:

Category Meaning
Current observed structure What inspected code, config, dependencies, registrations, call sites, and tests actually show
Approved intended structure Decisions with real approval source and scope
Proposals Suggestions and ADR candidates; they stay proposals
Unknown deployment behavior Anything repository evidence cannot establish, such as production topology or runtime traffic
Inspection limitations What was not read, and why

Folder and package names guide discovery; they do not establish architecture, usage, or approval. Repository config is evidence of configuration text, not of runtime behavior.

Decision conformance

Section titled “Decision conformance”

For drift checks, the Skill uses this pattern: approved decision → relevant repository evidence → Match / Deviation / Insufficient evidence.

  • A dependency reference alone does not prove runtime usage.
  • No ADR in the inspected scope means an observed pattern, not an approved mandate.
  • The decision’s actual wording is preserved. Code never rewrites it.

The Skill does not impose Clean Architecture, CQRS, MediatR, or any preferred stack. It reuses safe conventions and flags unsafe ones.

Procedure

Section titled “Procedure”
  1. Establish the question, the inspection boundary, relevant accepted decision IDs, and evidence gaps.
  2. Apply relevant dimensions from the procedure and the architecture standard (KIYO-ENG-003); trace real boundaries and consumers.
  3. Separate the five categories above.
  4. For conformance, use Match / Deviation / Insufficient evidence.
  5. Give every finding exact evidence, impact, explained confidence, and a proposed next action. No architecture scores.
  6. Choose the observation, impact, or drift report.
  7. Apply the Evidence Contract and the Architecture Definition of Done.

Example

Section titled “Example”
Illustrative request
Compare ADR-007 with this module; report deviations only.

A completed bounded review can report a Deviation without resolving it. The resolution is a separate human decision: either fix the code under Implement, or revise the decision with real approval.

Source and tests

Section titled “Source and tests”
Section titled “Related”