Ase Arch Analyze

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

*Determine* the *target programming language* and the *declared
architecture style* (if any) - e.g., Layered, Hexagonal
(Ports & Adapters), Onion, Clean, CQRS, Microservices,
Event-Driven, Modular Monolith - from code, project documentation,
README files, or folder structure.

Investigate the following architecture quality aspects across
7 thematic blocks:

**Block 1 - Component Boundaries**:

- **SA01 COMPONENT-RESPONSIBILITY**: each component (module,
  class, package) addresses exactly *one single concern* -
  i.e., has exactly *one reason to change*.
- **SA02 COMPONENT-GRANULARITY**: components have *appropriate
  size* - neither monolithic nor fragmented.
- **SA03 COMPONENT-HIERARCHY**: components placed at the *correct
  level* of the component hierarchy (system / program / module /
  class / function).

**Block 2 - Structural Organization**:

- **SA04 LAYERING**: *layers* (horizontal cuts) clearly
  separated, named, and ranked; no upward dependencies.
- **SA05 SLICING**: *slices* (vertical cuts - e.g., feature
  modules, bounded contexts) clearly separated and *cycle-free*.
- **SA06 DEPENDENCY-DIRECTION**: dependencies flow in exactly
  *one direction*; no *circular dependencies*.
- **SA07 REFERENCE-ARCHITECTURE**: *declared-style conformance* -
  the chosen architecture style (see STEP 1 intro for the
  recognized style list) is applied *consistently* throughout
  the codebase, without accidental mixing of styles.

**Block 3 - Architecture Principles**:

- **SA08 COUPLING**: *loose data coupling* between components -
  no *concrete-type dependencies* where abstractions exist, no
  shared data structures leaking across boundaries, communication
  via defined ports / facades / DTOs. (Runtime coupling such as
  races and shared mutable state is covered by SA17.)
- **SA09 COHESION**: *strong cohesion* within each component -
  internal parts (functions, fields, methods) are *tightly
  related*, *co-change*, and share data or behavior; scattered
  helpers that merely coexist by accident are flagged.
- **SA10 EXTENSIBILITY**: components are *open for extension*
  (plugins, SPIs, hooks) but *closed for modification*.
- **SA11 SEPARATION**: *cross-cutting concerns* (logging,
  security, caching, transactions, tracing) isolated from
  domain logic; trace context propagated across component
  boundaries.
- **SA12 ENCAPSULATION**: unavoidable complexity *encapsulated*
  behind a simple interface that *shields* its implementation
  details.

**Block 4 - Interface Quality**:

- **SA13 INTERFACE-SIZE**: each interface *proportional in size*
  to its functionality.
- **SA14 INTERFACE-COMPOSABILITY**: interface methods are
  *orthogonal* and enable combinatorial use-cases without
  boilerplate.
- **SA15 INTERFACE-CONTRACT**: each interface declares clear
  *syntactic* and *semantic* contracts (pre/post-conditions,
  invariants, idempotency, thread-safety).

**Block 5 - Quality Attributes**:

- **SA16 TESTABILITY**: architectural *seams* enable testing in
  isolation - dependency injection at component boundaries,
  mockable interfaces, side effects (DB, filesystem, network,
  time, randomness) hidden behind abstractions.
- **SA17 CONCURRENCY**: the *concurrency model* (event loop,
  threads, goroutines, async/await, actors, ...) is *explicitly
  chosen* and applied *consistently*. *Runtime coupling* -
  thread-safety boundaries, shared mutable state, races, lock
  hold times, async/sync boundaries - is explicit and localized;
  shared mutable state is protected.

**Block 6 - Architecture Governance**:

- **SA18 DECISION-RECORDS**: non-trivial architectural decisions
  are *documented* with rationale (Architecture Decision Records
  / ADRs, README sections, or in-code comments capturing *why*).
  The chosen style, deviations from defaults, and trade-offs are
  traceable.

**Block 7 - Package Cohesion**:

- **SA19 PACKAGE-COHESION**: each first-party package has a
  coherent role *and* topical theme - its members serve a
  common purpose, share a dominant noun-cluster, and have
  non-trivial cross-package use. Flag:
  - *grab-bag*: members split into ≥3 unrelated topical
    clusters (e.g. a `util` package mixing date-parsing,
    network-retry, and string-formatting helpers)
  - *misplaced class*: a class only imported once cross-package
    but referenced *≥3 times* inside the consumer (likely
    belongs in the consumer or in a shared utility package)
  - *topical outlier*: a class whose name-tokens share *<30%*
    overlap with the package's dominant noun-cluster, or with
    its `package-info` / `README` declaration when present
- **SA20 PACKAGE-CYCLE**: no *cyclic dependencies* between
  first-party packages - neither direct (`A → B` and `B → A`)
  nor transitive (via *Tarjan SCC* or pairwise scan). Each
  cycle is reported with the exact import lines that close it.
- **SA21 PACKAGE-SIZE**: package size and coupling shape are
  justified - flag packages at either extreme:
  - *god-package*: *incoming ≥ 5* and *outgoing ≥ 3* -
    coordinator dumping ground that should be split along its
    internal topical clusters
  - *fragment*: 1–2 files under a sibling parent that share a
    *name prefix* or *imported interface* with that sibling -
    consolidation candidate

Hints:

- During investigation, do *not* output anything else,
  especially do not give any further explanations or information.

- Focus on *practically relevant* problems and especially do
  *not* investigate theoretical or fictive cases.

- Focus on the *problem only* and do *not* investigate any
  possible *solution*.

- For the *target programming language*, apply each aspect
  according to its *idiomatic conventions* and *best practices*.

- *Control-flow verification* (SA17, SA08, SA06, SA11): for
  any claim about *ordering*, *lock hold time*, *thread
  boundary*, or *call from context X*, trace the actual
  acquire/release and call order line-by-line. Do not
  pattern-match on "loop inside method with lock" - verify
  which operations sit *between* the specific acquire and
  release in source order.

- *Package-graph construction (SA19–SA21)*: parse each file's
  import (or equivalent language construct) statement, keep
  only first-party packages within the analyzed scope, and
  persist two intermediate structures: the per-package
  incoming/outgoing class-edge map (drives SA20, SA21) and
  the per-package noun-token frequency table extracted from
  class names in camelCase / snake_case (drives SA19 topical
  analysis). No external NLP - pure tokens. Cite each finding
  with the exact import lines or class-name evidence.

- *Block 7 severity ladder*: SA20 (cycle) → HIGH; SA21
  (size/shape) → MEDIUM; SA19 (cohesion) → LOW. Mark ACCEPTED
  when `CLAUDE.md`, `AGENTS.md`, `package-info`, or class
  Javadoc explicitly justifies the pattern (per skill-meta
  contract-already-addressed rule).
</step>

2. Use the following output :

   Detected style: Target language:

   Hints:

   • For , name the detected architecture style or "undeclared" if none is documented.

   • For , build a Mermaid specification for a flowchart TB of the high-level component or layer structure and dispatch the rendering to the ase-meta-diagram sub-agent by calling the tool Agent(name: "ase-meta-diagram", description: "Diagram Rendering", subagent_type: "ase:ase-meta-diagram", prompt: <mermaid-spec/>), using its returned fenced code block verbatim. Show layers / slices / major components and their dependency direction.

   • Mark detected anomalies directly in the Mermaid source. Because ! and ? are Mermaid special characters, always quote anomaly-bearing node labels:

     • Problem node - prefix label with ! inside quotes: A["!ComponentA"].
     • Unclear node - suffix label with (?) inside quotes: B["ComponentB (?)"].
     • Cyclic edge - annotate the edge (not a node) with a cycle label on a bidirectional arrow: A <-- "cycle" --> B (or two labelled one-way edges if the renderer rejects <-->).

     The renderer preserves these glyphs verbatim inside the boxes and along the edges.

3. • Unpaired - single aspect violated, no partner in the tension matrix hit → emit PROBLEM template.
   • Paired - exactly two aspects of a single tension pair hit → emit TRADEOFF template (cluster of size 2).
   • Clustered - an aspect appears in multiple triggered tensions (e.g., SA10 hit against both SA12 and SA13) → collapse into one TRADEOFF with the recurring aspect as focal aspect and the others as partners. One direction for the whole cluster.

   Tension matrix (use to detect paired/clustered findings):

   ┌─────────────┬───────────────────────────────────────────────┐
   │    Pair     │                    Tension                    │
   ├─────────────┼───────────────────────────────────────────────┤
   │ SA01 ↔ SA02 │ single concern/responsibility vs. granularity │
   │ SA08 ↔ SA09 │ loose coupling vs. strong cohesion            │
   │ SA10 ↔ SA12 │ extensibility vs. encapsulation               │
   │ SA10 ↔ SA13 │ extensibility vs. interface size              │
   │ SA11 ↔ SA08 │ cross-cutting separation vs. coupling         │
   │ SA12 ↔ SA14 │ encapsulation vs. composability               │
   │ SA16 ↔ SA12 │ testability vs. encapsulation                 │
   │ SA16 ↔ SA13 │ testability vs. interface size                │
   │ SA05 ↔ SA09 │ slice cycle-freeness vs. cohesion             │
   │ SA06 ↔ SA10 │ single dependency direction vs. extensibility │
   └─────────────┴───────────────────────────────────────────────┘
   

   Report each unpaired finding with the following :

   Report each paired or clustered finding with the following :

   • Focal aspect: -
   • In tension with:

   RECOMMENDED: lean toward Reason: Implies:

   • :
   • ...

   For each partner in , repeat the *Implies* line, set to the partner aspect, and set to its brief implication. Set to the aspect direction the recommendation favors (the focal aspect or the partners).

   Hints:

   • For the final results, do not output anything else, especially do not give any further explanations or information.

   • For , and every entry in , name the aspect (e.g., SA06 DEPENDENCY-DIRECTION).

   • The is the aspect that participates in all tensions of the cluster. In a size-2 cluster both aspects participate equally in the single tension, so this rule cannot disambiguate; instead pick the focal aspect by the first applicable tiebreaker: (1) the aspect whose direction is more constrained by the detected style; else (2) the aspect carrying the higher finding severity; else (3) the aspect listed first in the tension matrix pair.

   • Brevity and precision: all free-form placeholders (, , partner-implications) are very brief but precise. is exactly one sentence grounded in the detected style, domain constraints, or language idioms - never generic principles.

   • Highlight code as <code/> and key aspects as .

   • Add inline references to related code positions in the form of either (<filename/>:<line-number/>), (<filename/>:<line-number/>-<line-number/>) or (<filename/>#<function-or-method/>).

   • Classify each finding with a of LOW, MEDIUM, HIGH, or ACCEPTED. Use ACCEPTED when the contract-already-addressed check applies (see skill meta rules on Findings).

   • Per-aspect consistency (mandatory): every aspect may appear in at most one output. Collapse both halves of a hit tension pair into a single TRADEOFF; if an aspect participates in multiple hit tensions, collapse all of them into one clustered TRADEOFF with that aspect as the focal aspect. Never emit contradictory recommendations for the same aspect, and never emit both halves of a tension pair as separate PROBLEMs.

   • Additionally, persist all reported findings in a single ase_kv_batch call to the ase MCP server with transactional set to true. The commands parameter array of this call starts with one { command: "clear", prefix: "ase-issue-" } entry (which removes only the previously persisted ase-issue-* keys, leaving any unrelated keys in the shared store intact), followed by one { command: "set", key: "ase-issue-P<n/>", val: "<title/>: <description/>" } entry per reported PROBLEM and one { command: "set", key: "ase-issue-T<n/>", val: "<title/>: <description/>" } entry per reported TRADEOFF.