Coupling Analysis Skill workflow skill. Use this skill when the user needs Analyzes coupling between modules using the three-dimensional model (strength, distance, volatility) from "Balancing Coupling in Software Design". Use when asking "are these modules too coupled?", "show me dependencies", "analyze integration quality", "which modules should I decouple?", "coupling report", or evaluating architectural health. Do NOT use for domain boundary analysis (use domain-analysis) or component sizing (use component-identification-sizing) and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
Coupling Analysis Skill workflow skill. Use this skill when the user needs Analyzes coupling between modules using the three-dimensional model (strength, distance, volatility) from "Balancing Coupling in Software Design". Use when asking "are these modules too coupled?", "show me dependencies", "analyze integration quality", "which modules should I decouple?", "coupling report", or evaluating architectural health. Do NOT use for domain boundary analysis (use domain-analysis) or component sizing (use component-identification-sizing) and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
This public intake copy packages packages/skills-catalog/skills/(architecture)/coupling-analysis from https://github.com/tech-leads-club/agent-skills into the native Omni Skills editorial shape without hiding its origin.
Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.
This intake keeps the copied upstream files intact and uses the external_source block in metadata.json plus ORIGIN.md as the provenance anchor for review.
Coupling Analysis Skill You are an expert software architect specializing in coupling analysis. You analyze codebases following the three-dimensional model from Balancing Coupling in Software Design (Vlad Khononov): 1. Integration Strength — what is shared between components 2. Distance — where the coupling physically lives 3. Volatility — how often components change The guiding balance formula: BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY A design is balanced when: - Tightly coupled components are close together (high strength + low distance = cohesion) - Distant components are loosely coupled (low strength + high distance = loose coupling) - Stable components (low volatility) can tolerate stronger coupling
Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Quick Heuristics, Known Limitations.
When to Use This Skill
Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.
Asks to "analyze coupling", "evaluate architecture", or "check dependencies"
Wants to understand integration strength between modules or services
Needs to identify problematic coupling or architectural smell
Wants to know if a module should be extracted or merged
References concepts like connascence, cohesion, or coupling from Khononov's book
Asks why changes in one module cascade to others unexpectedly
Operating Table
Situation
Start here
Why it matters
First-time use
metadata.json
Confirms repository, branch, commit, and imported path through the external_source block before touching the copied workflow
Provenance review
ORIGIN.md
Gives reviewers a plain-language audit trail for the imported source
Workflow execution
SKILL.md
Starts with the smallest copied file that materially changes execution
Supporting context
SKILL.md
Adds the next most relevant copied source file without loading the entire package
Handoff decision
## Related Skills
Helps the operator switch to a stronger native skill when the task drifts
Workflow
This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.
Full codebase or a specific area?
Primary level of abstraction: methods, classes, modules/packages, services?
Is git history available? (useful to estimate volatility)
Which parts are the business "core" (competitive differentiator)?
Which are infrastructure/generic support (auth, billing, logging)?
What changes most frequently according to the team?
Type - Volatility - Indicators
Imported Workflow Notes
Imported: Process
PHASE 1 — Context Gathering
Before analyzing code, collect:
1.1 Scope
Full codebase or a specific area?
Primary level of abstraction: methods, classes, modules/packages, services?
Is git history available? (useful to estimate volatility)
1.2 Business context — ask the user or infer from code:
Which parts are the business "core" (competitive differentiator)?
Which are infrastructure/generic support (auth, billing, logging)?
What changes most frequently according to the team?
This allows classifying subdomains (critical for volatility):
Type
Volatility
Indicators
Core subdomain
High
Proprietary logic, competitive advantage, area the business most wants to evolve
Supporting subdomain
Low
Simple CRUD, core support, no algorithmic complexity
Generic subdomain
Minimal
Auth, billing, email, logging, storage
PHASE 2 — Structural Mapping
2.1 Module inventory
For each module, record:
Name and location (namespace/package/path)
Primary responsibility
Declared dependencies (imports, DI, HTTP calls)
2.2 Dependency graph
Build a directed graph where:
Nodes = modules
Edges = dependencies (A → B means "A depends on B")
Note: the flow of knowledge is OPPOSITE to the dependency arrow
If A → B, then B is upstream and exposes knowledge to A (downstream)
2.3 Distance calculation
Use the encapsulation hierarchy to measure distance. The nearest common ancestor determines distance:
Common ancestor level
Distance
Example
Same method/function
Minimal
Two lines in same method
Same object/class
Very low
Methods on same object
Same namespace/package
Low
Classes in same package
Same library/module
Medium
Libs in same project
Different services
High
Distinct microservices
Different systems/orgs
Maximum
External APIs, different teams
Social factor: If modules are maintained by different teams, increase the estimated distance by one level (Conway's Law).
PHASE 3 — Integration Strength Analysis
For each dependency in the graph, classify the Integration Strength level (strongest to weakest):
INTRUSIVE COUPLING (Strongest — Avoid)
Downstream accesses implementation details of upstream that were not designed for integration.
Code signals:
Reflection to access private members
Service directly reading another service's database
Dependency on internal file/config structure of another module
Monkey-patching of internals (Python/Ruby)
Direct access to internal fields without getter
Effect: Any internal change to upstream (even without changing public interface) breaks downstream. Upstream doesn't know it's being observed.
FUNCTIONAL COUPLING (Second strongest)
Modules implement interrelated functionalities — shared business logic, interdependent rules, or coupled workflows.
Three degrees (weakest to strongest):
a) Sequential (Temporal) — modules must execute in specific order
connection.open() # must come first
connection.query() # depends on open
connection.close() # must come last
b) Transactional — operations must succeed or fail together
with transaction:
service_a.update(data)
service_b.update(data) # both must succeed
c) Symmetric (strongest) — same business logic duplicated in multiple modules
# Module Adefis_premium_customer(c): return c.purchases > 1000# Module B — duplicated rule! Must stay in syncdefqualifies_for_discount(c): return c.purchases > 1000
Note: symmetric coupling does NOT require modules to reference each other — they can be fully independent in code yet still have this coupling.
General signals of Functional Coupling:
Comments like "remember to update X when changing Y"
Cascading test failures when a business rule changes
Duplicated validation logic in multiple places
Need to deploy multiple services simultaneously for a feature
MODEL COUPLING (Third level)
Upstream exposes its internal domain model as part of the public interface. Downstream knows and uses objects representing the upstream's internal model.
Code signals:
# Analysis module uses Customer from CRM directlyfrom crm.models import Customer # CRM's internal modelclassAnalysis:
defprocess(self, customer_id):
customer = crm_repo.get(customer_id) # returns full Customer
status = customer.status # only needs status, but knows everything
// Service B consuming Service A's internal model via APIinterfaceCustomerFromServiceA {
internalAccountCode: string; // internal detail exposedlegacyId: number; // unnecessary internal field// ... many fields Service B doesn't need
}
Degrees (via static connascence):
connascence of name: knows field names of the model
connascence of type: knows specific types of the model
connascence of meaning: interprets specific values (magic numbers, internal enums)
connascence of algorithm: must use same algorithm to interpret data
connascence of position: depends on element order (tuples, unnamed arrays)
CONTRACT COUPLING (Weakest — Ideal)
Upstream exposes an integration-specific model (contract), separate from its internal model. The contract abstracts implementation details.
Code signals:
classCustomerSnapshot: # integration DTO, not the internal model"""Public integration contract — stable and intentional."""id: str
status: str# enum converted to string
tier: str# only what consumers need @staticmethoddeffrom_customer(customer: Customer) -> 'CustomerSnapshot':
return CustomerSnapshot(
id=str(customer.id),
status=customer.status.value,
tier=customer.loyalty_tier.display_name
)
Characteristics of good Contract Coupling:
Dedicated DTOs/ViewModels per use case (not the domain model)
Patterns: Facade, Adapter, Anti-Corruption Layer, Published Language (DDD)
PHASE 4 — Volatility Assessment
For each module, estimate volatility based on:
4.1 Subdomain type (preferred) — see table in Phase 1
4.2 Git analysis (when available):
# Commits per file in the last 6 months
git log --since="6 months ago" --format="" --name-only | sort | uniq -c | sort -rn | head -20
# Files that change together frequently (temporal coupling)# High co-change = possible undeclared functional coupling
4.3 Code signals:
Many TODO/FIXME → area under evolution (higher volatility)
Many API versions (V1, V2, V3) → frequently changing area
Fragile tests that break constantly → volatile area
Comments "business rule: ..." → business logic = probably core
4.4 Inferred volatility
Even a supporting subdomain module may have high volatility if:
It has Intrusive or Functional coupling with core subdomain modules
🟡 ACCEPTABLE — Strong but stable (e.g. legacy integration)
High
Low
High
🟢 GOOD — High cohesion (change together, live together)
High
Low
Low
🟢 GOOD — Strong but static
Low
High
High
🟢 GOOD — Loose coupling (separate and independent)
Low
High
Low
🟢 GOOD — Loose coupling and stable
Low
Low
High
🟠 ATTENTION — Local complexity (mixes unrelated components)
Low
Low
Low
🟡 ACCEPTABLE — May generate noise, but low cost
PHASE 6 — Analysis Report
Structure the report in sections:
6.1 Executive Summary
CODEBASE: [name]
MODULES ANALYZED: N
DEPENDENCIES MAPPED: N
CRITICAL ISSUES: N
MODERATE ISSUES: N
OVERALL HEALTH SCORE: [Healthy / Attention / Critical]
ISSUE: [descriptive name]
────────────────────────────────────────
Modules involved: A → B
Coupling type: Functional Coupling (symmetric)
Connascence level: Connascence of Value
Evidence in code:
[snippet or description of found pattern]
Dimensions:
• Strength: HIGH (Functional - symmetric)
• Distance: HIGH (separate services)
• Volatility: HIGH (core subdomain)
Balance Score: CRITICAL 🔴
Maintenance: High — frequent changes propagate over long distance
Impact: Any change to business rule [X] requires simultaneous
update in [A] and [B], which belong to different teams.
Recommendation:
→ Extract shared logic to a dedicated module that both can
reference (DRY + contract coupling)
→ Or: Accept duplication and explicitly document the coupling
(if volatility is lower than it appears)
6.4 Positive Patterns Found
✅ [ModuleX] uses dedicated integration DTOs — contract coupling well implemented
✅ [ServiceY] exposes only necessary data via API — minimizes model coupling
✅ [PackageZ] encapsulates its internal model well — low implementation leakage
6.5 Prioritized Recommendations
High priority (high impact, blocking evolution):
...
Medium priority (improve architectural health): 2. ...
Low priority (incremental improvements): 3. ...
Imported: Quick Heuristics
For Integration Strength:
"If I change an internal detail of module X, how many other modules need to change?"
"Was the integration contract designed to be public, or is it accidental?"
"Is there duplicated business logic that must be manually synchronized?"
For Distance:
"What's the cost of making a change that affects both modules?"
"Do teams maintaining these modules need to coordinate deployments?"
"If one module fails, does the other stop working?"
For Volatility:
"Does this module encapsulate competitive business advantage?"
"Does the business team frequently request changes in this area?"
"Is there a history of many refactors in this area?"
For Balance:
"Do components that need to change together live together in the code?"
"Are independent components well separated?"
"Where is there strong coupling with volatile and distant components?" (→ this is the main problem)
Examples
Example 1: Ask for the upstream workflow directly
Use @coupling-analysis to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.
Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.
Example 2: Ask for a provenance-grounded review
Review @coupling-analysis against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.
Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.
Example 3: Narrow the copied support files before execution
Use @coupling-analysis for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.
Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.
Example 4: Build a reviewer packet
Review @coupling-analysis using the copied upstream files plus provenance, then summarize any gaps before merge.
Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.
Best Practices
Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.
Keep the imported skill grounded in the upstream repository; do not invent steps that the source material cannot support.
Prefer the smallest useful set of support files so the workflow stays auditable and fast to review.
Keep provenance, source commit, and imported file paths visible in notes and PR descriptions.
Point directly at the copied upstream files that justify the workflow instead of relying on generic review boilerplate.
Treat generated examples as scaffolding; adapt them to the concrete task before execution.
Route to a stronger native skill when architecture, debugging, design, or security concerns become dominant.
Troubleshooting
Problem: The operator skipped the imported context and answered too generically
Symptoms: The result ignores the upstream workflow in packages/skills-catalog/skills/(architecture)/coupling-analysis, fails to mention provenance, or does not use any copied source files at all.
Solution: Re-open metadata.json, ORIGIN.md, and the most relevant copied upstream files. Check the external_source block first, then restate the provenance before continuing.
Problem: The imported workflow feels incomplete during review
Symptoms: Reviewers can see the generated SKILL.md, but they cannot quickly tell which references, examples, or scripts matter for the current task.
Solution: Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.
Problem: The task drifted into a different specialization
Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better.
Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.
Related Skills
@accessibility - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-cold-outreach - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-pricing - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-sdr - Use when the work is better handled by that native specialization after this imported skill establishes context.
Additional Resources
Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.
Resource family
What it gives the reviewer
Example path
references
copied reference notes, guides, or background material from upstream
references/n/a
examples
worked examples or reusable prompts copied from upstream
examples/n/a
scripts
upstream helper scripts that change execution or validation
scripts/n/a
agents
routing or delegation notes that are genuinely part of the imported package
agents/n/a
assets
supporting assets or schemas copied from the source package
