RepoSkillOpt — As-Is Architecture Analysis (Canonical Skill)

Purpose

This is the repo-specializing analysis layer of RepoSkillOpt. The generic understanding skill (

repo-skillopt

) is unchanged — it produces the repo-neutral Repository Specification. This skill specializes on a specific repository: it deepens that Repository Specification into an evidence-grounded view of the current architecture and answers "what would a change ripple into?" — before anything is touched. It produces an Architecture View and a Change-Impact (blast-radius) Analysis, and is the analyze as-is stage the plan to-be skill (

repo-orchestration

) consumes. The skill's own content is vendor-neutral (no coding-agent runtime dependency); its output is repo-specific.

Trigger Conditions

Activate when the user asks to map the architecture, assess dependencies/coupling/layering, or evaluate "what would change if we… / is it safe to change X" — or recognizable equivalents. Do not activate for unrelated requests.

Prerequisite

A Repository Specification (

.reposkillopt/specs/repository-specification.md

). If absent, state the prerequisite and point the user to the repository-understanding skill; do not fabricate an architecture from shallow inspection.

Operating Principles

Build on the spec, corroborate against code. The Repository Specification is the starting evidence; verify every architectural claim against the actual files, configs, and call sites.
Ground every major claim. Each carries exactly one label —
```
**[fact]**
```
,
```
**[inference]**
```
,
```
**[unknown]**
```
,
```
**[human]**
```
;
```
**[fact]**
```
MUST carry a resolvable
```
file:line
```
/symbol citation.
No silent omission. Unresolvable structure or impact is
```
**[unknown]**
```
with the reason, never dropped.
Do not overclaim. Do not describe layers or flows you have not traced; mark inference as inference.
Repository facts stay repository-scoped. Only patterns explicitly marked candidate-for-generic may enter the skill-convergence loop.

Workflow

(a) Read the Repository Specification and the entrypoints, manifests, and core modules it cites.

(b) Architecture View (

.reposkillopt/architecture/architecture-view.md

, per

templates/architecture-view.md

): C4-style levels — Context (system + external actors), Containers (runtime/deployable units), Components (modules within containers) — plus Key sequences (end-to-end flows, cited at each hop) and a Dependency graph (cited internal edges). Every component and edge cites a real

file:line

. Diagrams (

graph

sequenceDiagram

) are visual aids and carry no citations; every node/edge they show also appears as a cited line.

.reposkillopt/impact/change-impact-analysis.md

, per

templates/change-impact-analysis.md

): for the named target/change, the affected modules, tests, contracts, and call sites — each row with a confidence label (high|medium|low) tied to evidence strength (direct cited call site = high; name-resolution/inference = medium; dynamic/unresolved = low and

**[unknown]**

) and a citation. Locate impact with a fast scanner (

rg

grep

) and read only the matched lines you cite.

(d) Deterministic completeness gate. Before finishing, the artifacts MUST pass the deterministic checks (

check_architecture_view

check_impact_analysis

): every component/edge cited and resolvable; every impact row carries a citation and a confidence label.

Output Discipline

Labels:

**[fact]**

(verified; cited),

**[inference]**

(state the basis),

**[unknown]**

(also listed as such),

**[human]**

(cite the Feedback Item id). Citations use

path:line

path:start-end

path:Symbol[:line]

, or

cmd:

output:

. Trivial recitations need no label.

Human Feedback Loop

Corrections are recorded as Feedback Items (

templates/human-feedback.md

) under

.reposkillopt/feedback/

and applied to the artifact in place. Repository-specific corrections stay repository-scoped.

Skill Convergence Loop

When recurrent feedback (≥3 related items) marked candidate-for-generic reveals a weakness in this skill, draft a Skill Edit Proposal (

templates/skill-edit-proposal.md

). It may be accepted only after passing the validation gate (

rubric/validation-gate.md

): regenerate the artifacts for a disjoint held-out reference set with no per-dimension rubric regression (see

rubric/asis-architecture-rubric.md

) and the deterministic checks still passing. Nothing is silently promoted; acceptance bumps the version + adds a CHANGELOG entry. Mirror every accepted edit into the four adapters (adapter-equivalence).

repo-architecture

NPX Install

Tags

SKILL.md Content