{"id":"3c153b54-f7a0-4cc5-8181-c22f16e79f9b","entityType":"agent","slug":"clawhub-athola-nm-pensive-architecture-review","name":"architecture-review","canonicalUrl":"https://www.xpersona.co/agent/clawhub-athola-nm-pensive-architecture-review","canonicalPath":"/agent/clawhub-athola-nm-pensive-architecture-review","generatedAt":"2026-10-10T05:59:43.780Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T04:36:31.067Z","emptyReason":null},"description":"Assesses architecture decisions, ADR compliance, and coupling Skill: architecture-review Owner: athola Summary: Assesses architecture decisions, ADR compliance, and coupling Tags: latest:1.9.19 Version history: v1.9.19 | 2026-08-26T13:18:21.040Z | user Release v1.9.19 v1.9.17 | 2026-07-30T05:38:38.297Z | user Release v1.9.17 v1.9.16 | 2026-07-14T19:55:19.195Z | user Release v1.9.16 v1.9.14 | 2026-06-30T18:03:45.240Z | user Release v1.9.14 v1.9.13 | 2026-06-27T16:21:51.074Z | us","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.7K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17emme0e2m3cpf7k2jvp3a84984b8z9:nm-pensive-architecture-review","sourceUrl":"https://clawhub.ai/athola/nm-pensive-architecture-review","homepage":"https://clawhub.ai/athola/skills/nm-pensive-architecture-review","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/athola/nm-pensive-architecture-review","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/athola/skills/nm-pensive-architecture-review","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Assesses architecture decisions, ADR compliance, and coupling Skill: architecture-review Owner: athola Summary: Assesses architecture decisions, ADR compliance,"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:36:31.067Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:36:31.067Z","emptyReason":null},"stars":null,"forks":null,"downloads":1680,"packageName":null,"latestVersion":"1.9.19","tractionLabel":"1.7K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:36:31.067Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T04:36:31.067Z","lastCrawledAt":"2026-10-10T04:36:31.067Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T04:36:31.067Z","lastVerifiedAt":null,"highlights":[{"version":"1.9.19","createdAt":"2026-08-26T13:18:21.040Z","changelog":"Release v1.9.19","fileCount":7,"zipByteSize":15283},{"version":"1.9.17","createdAt":"2026-07-30T05:38:38.297Z","changelog":"Release v1.9.17","fileCount":7,"zipByteSize":15286},{"version":"1.9.16","createdAt":"2026-07-14T19:55:19.195Z","changelog":"Release v1.9.16","fileCount":7,"zipByteSize":15277},{"version":"1.9.14","createdAt":"2026-06-30T18:03:45.240Z","changelog":"Release v1.9.14","fileCount":7,"zipByteSize":15461},{"version":"1.9.13","createdAt":"2026-06-27T16:21:51.074Z","changelog":"Release v1.9.13","fileCount":7,"zipByteSize":15327},{"version":"1.9.12","createdAt":"2026-06-19T03:16:53.551Z","changelog":"Release v1.9.12","fileCount":7,"zipByteSize":15244},{"version":"1.0.3","createdAt":"2026-06-18T14:11:45.344Z","changelog":"Release v1.9.12","fileCount":7,"zipByteSize":15350},{"version":"1.0.2","createdAt":"2026-05-09T02:19:07.394Z","changelog":"Release v1.9.5","fileCount":7,"zipByteSize":14455}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17emme0e2m3cpf7k2jvp3a84984b8z9:nm-pensive-architecture-review","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T05:59:43.775Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-athola-nm-pensive-architecture-review/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T04:36:31.067Z","emptyReason":null},"readme":"Skill: architecture-review\n\nOwner: athola\n\nSummary: Assesses architecture decisions, ADR compliance, and coupling\n\nTags: latest:1.9.19\n\nVersion history:\n\nv1.9.19 | 2026-08-26T13:18:21.040Z | user\n\nRelease v1.9.19\n\nv1.9.17 | 2026-07-30T05:38:38.297Z | user\n\nRelease v1.9.17\n\nv1.9.16 | 2026-07-14T19:55:19.195Z | user\n\nRelease v1.9.16\n\nv1.9.14 | 2026-06-30T18:03:45.240Z | user\n\nRelease v1.9.14\n\nv1.9.13 | 2026-06-27T16:21:51.074Z | user\n\nRelease v1.9.13\n\nv1.9.12 | 2026-06-19T03:16:53.551Z | user\n\nRelease v1.9.12\n\nv1.0.3 | 2026-06-18T14:11:45.344Z | user\n\nRelease v1.9.12\n\nv1.0.2 | 2026-05-09T02:19:07.394Z | user\n\nRelease v1.9.5\n\nv1.0.1 | 2026-05-06T14:20:19.219Z | user\n\nRelease v1.9.4\n\nv1.0.0 | 2026-04-14T17:01:59.554Z | auto\n\nInitial release of the Architecture Review skill.\n\n- Provides a structured workflow for reviewing architecture decisions, ADR compliance, coupling, and design principles.\n- Includes progressive module loading for ADR audits, coupling analysis, principle checks, and methodology review.\n- Offers a checklist covering coupling, cohesion, layering, and evolution principles.\n- Specifies required TodoWrite items and step-by-step workflow for running reviews.\n- Contains troubleshooting guidance and quick start instructions.\n\nArchive index:\n\nArchive v1.9.19: 7 files, 15283 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), skill-card.md (2058b), SKILL.md (7846b), _meta.json (150b)\n\nFile v1.9.19:SKILL.md\n\n---\nname: architecture-review\ndescription: Assesses architecture decisions, ADR compliance, and coupling\nversion: 1.9.8\ntriggers:\n  - architecture\n  - design\n  - adr\n  - coupling\n  - patterns\n  - principles\n  - evaluating design changes or validating structural decisions before merging\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/athola/claude-night-market/tree/master/plugins/pensive\", \"emoji\": \"\\ud83c\\udfd7\\ufe0f\", \"requires\": {\"config\": [\"night-market.pensive:shared\", \"night-market.imbue:proof-of-work\", \"night-market.imbue:diff-analysis/modules/risk-assessment-framework\"]}}}\nsource: claude-night-market\nsource_plugin: pensive\n---\n\n> **Night Market Skill** — ported from [claude-night-market/pensive](https://github.com/athola/claude-night-market/tree/master/plugins/pensive). For the full experience with agents, hooks, and commands, install the Claude Code plugin.\n\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [When to Use](#when-to-use)\n- [Progressive Loading](#progressive-loading)\n- [Required TodoWrite Items](#required-todowrite-items)\n- [Workflow](#workflow)\n- [Step 1: Establish Context (`arch-review:context-established`)](#step-1:-establish-context-(arch-review:context-established))\n- [Step 2: ADR Audit (`arch-review:adr-audit`)](#step-2:-adr-audit-(arch-review:adr-audit))\n- [Step 3: Interaction Mapping (`arch-review:interaction-mapping`)](#step-3:-interaction-mapping-(arch-review:interaction-mapping))\n- [Step 4: Principle Checks (`arch-review:principle-checks`)](#step-4:-principle-checks-(arch-review:principle-checks))\n- [Step 5: Risks and Actions (`arch-review:risks-actions`)](#step-5:-risks-and-actions-(arch-review:risks-actions))\n- [Testing](#testing)\n\n## Testing\n\nRun `pytest plugins/pensive/tests/skills/test_architecture_review.py` to verify review logic.\n- [Architecture Principles Checklist](#architecture-principles-checklist)\n- [Coupling](#coupling)\n- [Cohesion](#cohesion)\n- [Layering](#layering)\n- [Evolution](#evolution)\n\n\n# Architecture Review Workflow\n\nArchitecture assessment against ADRs and design principles.\n\n## Quick Start\n\n```bash\n/architecture-review\n```\n\n## When To Use\n\n- Approving reimplementations.\n- Large-scale refactoring reviews.\n- System design changes.\n- New module/service introduction.\n- Dependency restructuring.\n\n## When NOT To Use\n\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n\n## Progressive Loading\n\nLoad modules based on review scope:\n\n- **`modules/adr-audit.md`** (~400 tokens): ADR verification and documentation.\n- **`modules/coupling-analysis.md`** (~450 tokens): Dependency analysis and boundary violations.\n- **`modules/principle-checks.md`** (~500 tokens): Code quality, security, and performance.\n- **`modules/fpf-methodology.md`** (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.\n\nLoad all modules for full reviews. For focused reviews, load only relevant modules.\n\n## Required TodoWrite Items\n\n1. `arch-review:context-established`: Repository, branch, motivation.\n2. `arch-review:adr-audit`: ADR verification and new ADR needs.\n3. `arch-review:interaction-mapping`: Module coupling analysis.\n4. `arch-review:invariant-check`: Invariant conflict detection and 3-option analysis.\n5. `arch-review:principle-checks`: LoD, security, performance.\n6. `arch-review:risks-actions`: Recommendation and follow-ups.\n\n## Workflow\n\n### Step 1: Establish Context (`arch-review:context-established`)\n\nConfirm repository and branch:\n```bash\npwd\ngit status -sb\n```\n\nDocument:\n- Feature/bug/epic motivating review.\n- Affected subsystems.\n- Architectural intent from README/docs.\n- Design trade-off assumptions.\n\n### Step 2: ADR Audit (`arch-review:adr-audit`)\n\n**Load: `modules/adr-audit.md`**\n\n- Locate ADRs in project.\n- Verify required sections.\n- Check status flow.\n- Confirm immutability compliance.\n- Flag need for new ADRs.\n\n### Step 3: Interaction Mapping (`arch-review:interaction-mapping`)\n\n**Load: `modules/coupling-analysis.md`**\n\n- Diagram before/after module interactions.\n- Verify composition boundaries.\n- Check data ownership clarity.\n- Validate dependency flow direction.\n- Identify coupling violations.\n\n### Step 3.5: Invariant Conflict Detection (`arch-review:invariant-check`)\n\nBefore checking principles, identify whether the changes\nconflict with existing design invariants. This is the\nhighest-judgment step in architecture review — models\nget this wrong more often than any other call.\n\n**Identify existing invariants:**\n\n1. Scan ADRs for recorded decisions still in \"accepted\"\n   status\n2. Check module boundaries (are imports crossing layers\n   that previously didn't?)\n3. Check data flow direction (does data now flow in a\n   new direction?)\n4. Check API contracts (are public interfaces changing\n   shape?)\n5. Check structural patterns (is a new pattern being\n   introduced alongside an existing one?)\n\n```bash\n# Detect boundary crossings in changed files\ngit diff --name-only | while read f; do\n  head -20 \"$f\" 2>/dev/null | rg \"^(import|from|use |require)\" || true\ndone\n```\n\n**When a conflict is detected:**\n\nDo NOT recommend a resolution. Present the three options\nand escalate to human judgment:\n\n| Option | When Right | When Wrong |\n|--------|------------|------------|\n| **Preserve invariant** (reject feature) | Invariant simplifies many things; feature is marginal | Feature is genuinely needed and invariant is stale |\n| **Layer on top** (add inelegantly) | Feature is needed; invariant still valuable; imperfection is OK | Layering creates a maintenance trap that will compound |\n| **Revise invariant** (change the design) | Genuine new learning invalidates the original reasoning | You're \"cleaning up\" a decision you don't fully understand |\n\n**Output format:**\n\n```markdown\n### Invariant Conflicts\n\n[I1] **[Invariant name]** — [what decision it represents]\n- **Conflict**: [what change clashes]\n- **Options**: Preserve / Layer / Revise\n- **Recommendation**: ESCALATE TO HUMAN\n- **Risk if wrong**: [what compounds]\n```\n\n**Why this matters:** Bad invariant decisions compound.\nAfter a few wrong calls the codebase becomes\nunsalvageable. This is a judgment problem, not a context\nproblem — the agent should surface it, not solve it.\n\n### Step 4: Principle Checks (`arch-review:principle-checks`)\n\n**Load: `modules/principle-checks.md`**\n\n- Law of Demeter.\n- Anti-slop patterns.\n- Security (input validation, least privilege).\n- Performance (N+1 queries, caching).\n\n### Step 5: Risks and Actions (`arch-review:risks-actions`)\n\nSummarize using `imbue:diff-analysis/modules/risk-assessment-framework`:\n- Current vs proposed architecture.\n- Business impact.\n- Technical debt implications.\n\nList follow-ups with owners and dates.\n\nProvide recommendation:\n- **Approve**: Architecture sound.\n- **Approve with actions**: Minor issues to address.\n- **Block**: Fundamental problems requiring redesign.\n\n## Architecture Principles Checklist\n\n### Coupling\n- [ ] Dependencies follow defined boundaries.\n- [ ] No circular dependencies.\n- [ ] Extension points used properly.\n- [ ] Abstractions don't leak.\n\n### Cohesion\n- [ ] Related functionality grouped.\n- [ ] Single responsibility per module.\n- [ ] Clear module purposes.\n\n### Layering\n- [ ] Layers have clear responsibilities.\n- [ ] Dependencies flow downward.\n- [ ] No layer bypassing.\n\n### Invariants\n- [ ] Existing design invariants identified.\n- [ ] Conflicts between changes and invariants surfaced.\n- [ ] Three-option analysis (preserve/layer/revise) presented.\n- [ ] Invariant changes escalated to human judgment.\n- [ ] No silent invariant revisions in the diff.\n\n### Evolution\n- [ ] Changes are reversible.\n- [ ] Migration paths are clear.\n- [ ] ADRs document decisions.\n\nFile v1.9.19:_meta.json\n\n{\n  \"ownerId\": \"kn7d107jg9jv602h9ytsegydq184a42s\",\n  \"slug\": \"nm-pensive-architecture-review\",\n  \"version\": \"1.9.19\",\n  \"publishedAt\": 1787750301040\n}\n\nFile v1.9.19:modules/adr-audit.md\n\n---\nname: adr-audit\ndescription: Architecture Decision Record audit patterns and verification workflows\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [adr, documentation, governance, decisions]\ncomplexity: intermediate\nestimated_tokens: 400\n---\n\n# ADR Audit Module\n\ndetailed ADR discovery, validation, and governance patterns.\n\n## ADR Location Patterns\n\nCommon ADR locations by project type:\n\n```bash\n# Standard locations\nwiki/architecture/\ndocs/adr/\ndocs/decisions/\narchitecture/decisions/\n.adr/\n\n# Search pattern\nfind . -type f -name \"*ADR*\" -o -name \"*decision*\" | grep -E \"\\.(md|txt)$\"\n```\n\n## Required ADR Sections\n\nEvery ADR must include:\n\n### 1. Title\nClear, specific decision statement:\n- \"Use PostgreSQL for primary datastore\"\n- \"Adopt hexagonal architecture pattern\"\n- \"Implement JWT-based authentication\"\n\n### 2. Status\nMust follow strict progression:\n```\nProposed → Reviewed → Accepted\n                    ↓\n              Superseded (when invalidated)\n```\n\n**Rules:**\n- Status changes are append-only\n- Date each status transition\n- Never delete/modify accepted ADRs\n- Use \"Superseded by ADR-XXX\" to replace\n\n### 3. Context\nDocument the forces at play:\n- Business requirements\n- Technical constraints\n- Team capabilities\n- Timeline pressures\n- Existing architecture\n\n### 4. Decision\nThe \"we will...\" statement:\n- Clear action chosen\n- Implementation approach\n- Key design choices\n\n### 5. Alternatives Considered\nFor each alternative:\n- Description\n- Pros/cons\n- Why rejected\n\nMinimum 2 alternatives required.\n\n### 6. Consequences\n\n**Positive:**\n- Benefits gained\n- Problems solved\n- Capabilities enabled\n\n**Negative:**\n- Trade-offs accepted\n- Technical debt incurred\n- Complexity added\n\n**Neutral:**\n- Changes required\n- Migration steps\n- Training needs\n\n### 7. Metadata\n```yaml\nDate: YYYY-MM-DD\nAuthor: [name]\nStatus: [status]\nSupersedes: [ADR-XXX] (if applicable)\nSuperseded-by: [ADR-XXX] (if applicable)\n```\n\n## Status Flow Verification\n\n### Valid Transitions\n- Proposed → Reviewed\n- Reviewed → Accepted\n- Reviewed → Rejected\n- Accepted → Superseded (via new ADR only)\n\n### Invalid Transitions\n- Proposed -> Accepted (skip review)\n- Accepted -> Rejected (use Superseded)\n- Superseded -> Accepted (immutable)\n\n## Immutability Rules\n\n**Once Accepted:**\n1. **Never modify** decision content\n2. **Never change** consequences\n3. **Never delete** the ADR\n4. **Only append** status changes\n\n**To Replace:**\n1. Create new ADR with superseding decision\n2. Add \"Supersedes: ADR-XXX\" to new ADR\n3. Add \"Superseded-by: ADR-YYY\" to old ADR\n4. Update old ADR status to \"Superseded\"\n\n## Audit Workflow\n\n### 1. Locate All ADRs\n```bash\n# Find ADR directory\nls -la docs/adr/ wiki/architecture/ 2>/dev/null\n\n# Count ADRs\nfind . -path \"*/adr/*.md\" -o -path \"*/decisions/*.md\" | wc -l\n```\n\n### 2. Verify Structure\nFor each ADR:\n- [ ] Has all required sections\n- [ ] Status follows valid flow\n- [ ] Dates are present\n- [ ] Alternatives documented (≥2)\n- [ ] Consequences specified\n\n### 3. Check References\n```bash\n# Find ADR references in code\ngrep -r \"ADR-[0-9]\" --include=\"*.md\" --include=\"*.py\" --include=\"*.js\"\n\n# Verify backlinks\ngrep \"Superseded-by\" docs/adr/*.md\n```\n\n### 4. Flag Issues\nCommon problems:\n- Missing sections\n- Invalid status transitions\n- Modified accepted ADRs\n- Missing supersession links\n- Insufficient alternatives\n\n## New ADR Requirements\n\nFlag need for new ADR when:\n- Introducing new architectural pattern\n- Changing core technology\n- Modifying system boundaries\n- Adding external dependencies\n- Changing security model\n\n**Before implementation:**\n1. Draft ADR with all sections\n2. Set status: Proposed\n3. Request review\n4. Update to Reviewed\n5. Gain approval → Accepted\n6. Then proceed with implementation\n\n## Integration with Architecture Review\n\nUse this module during Step 2 (ADR Audit):\n1. Locate ADRs using patterns\n2. Verify structure completeness\n3. Check status flow validity\n4. Confirm immutability compliance\n5. Identify missing ADRs for current work\n6. Draft new ADRs if needed\n\nFile v1.9.19:modules/coupling-analysis.md\n\n---\nname: coupling-analysis\ndescription: Interaction mapping, composition boundaries, and dependency flow analysis\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [coupling, dependencies, composition, boundaries, modularity]\ncomplexity: advanced\nestimated_tokens: 450\n---\n\n# Coupling Analysis Module\n\nSystematic analysis of module interactions, boundaries, and dependency flows.\n\n## Interaction Mapping Patterns\n\n### Visual Representation\n\nCreate before/after diagrams:\n\n```\nBefore:\n┌─────────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│Module B │────▶│ Database │\n└─────────┘     └─────────┘     └──────────┘\n\nAfter:\n┌─────────┐     ┌───────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│ Cache │────▶│Module B │────▶│ Database │\n└─────────┘     └───────┘     └─────────┘     └──────────┘\n```\n\n### Dependency Graph Tools\n\n```bash\n# Python: Generate import graph\npydeps --max-bacon=2 --cluster src/\n\n# TypeScript: Analyze module dependencies\nmadge --circular --extensions ts src/\n\n# Generic: Find direct dependencies\ngrep -r \"import\\|require\\|from\" src/ | cut -d: -f1 | sort | uniq -c\n```\n\n## Composition Boundaries\n\n### Boundary Definition\n\nClear boundaries have:\n1. **Explicit interfaces** - Published contracts\n2. **Data ownership** - Single source of truth\n3. **Encapsulation** - Hidden implementation\n4. **Stability** - Minimal breaking changes\n\n### Boundary Types\n\n**Module Boundaries:**\n```\n┌──────────────────────────┐\n│   Public API             │\n├──────────────────────────┤\n│   Internal Logic         │\n│   (implementation)       │\n└──────────────────────────┘\n```\n\n**Layer Boundaries:**\n```\n┌──────────────────────────┐\n│   Presentation Layer     │ ← HTTP/UI\n├──────────────────────────┤\n│   Application Layer      │ ← Business Logic\n├──────────────────────────┤\n│   Domain Layer           │ ← Core Models\n├──────────────────────────┤\n│   Infrastructure Layer   │ ← Database/External\n└──────────────────────────┘\n```\n\n**Service Boundaries:**\n```\nService A          Service B\n┌────────┐        ┌────────┐\n│  API   │◀──────▶│  API   │\n├────────┤        ├────────┤\n│  DB A  │        │  DB B  │\n└────────┘        └────────┘\n```\n\n### Boundary Violations\n\n**Ad-hoc Reach-ins:**\n```python\n# Bad: Reaching through module boundary\nuser.profile.settings.theme.get_color()\n\n# Good: Ask for what you need\nuser.get_theme_color()\n```\n\n**Layering Violations:**\n```python\n# Bad: Domain layer accessing infrastructure\nclass Order:\n    def save(self):\n        db.execute(\"INSERT INTO orders...\")\n\n# Good: Infrastructure handles persistence\nclass OrderRepository:\n    def save(self, order: Order):\n        db.execute(\"INSERT INTO orders...\")\n```\n\n## Data Ownership Analysis\n\n### Single Owner Principle\n\nEach data entity has exactly one authoritative owner:\n\n```\nUser Data:\n├── Auth Service (owner: credentials)\n├── Profile Service (owner: profile data)\n└── Analytics Service (consumer: read-only)\n```\n\n### Ownership Violations\n\n**Multiple Writers:**\n```python\n# Bad: Two services modify same data\nauth_service.update_user_email()\nprofile_service.update_user_email()\n\n# Good: Single owner\nprofile_service.update_email()  # Publishes event\nauth_service.handle_email_changed()  # Subscribes to event\n```\n\n**Ownership Leaks:**\n```python\n# Bad: Exposing internal structure\ndef get_user():\n    return user_database_model\n\n# Good: Return boundary type\ndef get_user():\n    return UserDTO(id=..., name=...)\n```\n\n## Dependency Flow Checking\n\n### Expected Flow Patterns\n\n**Layered Architecture:**\n```\nPresentation → Application → Domain → Infrastructure\n     ↓              ↓           ↓            ↓\n  (no reverse dependencies allowed)\n```\n\n**Hexagonal Architecture:**\n```\n     ┌─────────────┐\n     │   Domain    │ ← Core (no dependencies)\n     └──────┬──────┘\n            │\n  ┌─────────┴─────────┐\n  │   Application     │ ← Orchestration\n  └────────┬──────────┘\n           │\n  ┌────────┴─────────┐\n  │   Adapters       │ ← External interfaces\n  └──────────────────┘\n```\n\n### Circular Dependency Detection\n\n```bash\n# Python\npydeps --show-cycles src/\n\n# JavaScript/TypeScript\nmadge --circular src/\n\n# Manual check\ngrep -r \"from.*import\" src/ | # Extract all imports\n  python -c \"\nimport sys\nfrom collections import defaultdict\n\ngraph = defaultdict(set)\nfor line in sys.stdin:\n    # Parse: file imports module\n    # Build graph, detect cycles\n\"\n```\n\n### Dependency Metrics\n\n**Afferent Coupling (Ca):**\nNumber of modules that depend on this module.\n- High Ca = Stable (many dependents)\n\n**Efferent Coupling (Ce):**\nNumber of modules this module depends on.\n- High Ce = Unstable (many dependencies)\n\n**Instability (I):**\n```\nI = Ce / (Ca + Ce)\n```\n- I = 0: Maximally stable\n- I = 1: Maximally unstable\n\n### Ideal Patterns\n\n**Stable Abstractions:**\n- Core domain: Low I (stable)\n- Infrastructure: High I (unstable, replaceable)\n\n**Dependency Direction:**\n```\nUnstable → Stable\n(changing) depends on (stable)\n```\n\n## Side Effects Analysis\n\n### Side Effect Categories\n\n**1. State Mutations:**\n```python\n# Track mutations\ndef process_order(order):\n    order.status = \"PROCESSED\"  # Mutation\n    notify_customer(order)       # Side effect\n    log_event(order)            # Side effect\n```\n\n**2. External I/O:**\n- Database writes\n- API calls\n- File operations\n- Message queue publishing\n\n**3. Timing Dependencies:**\n- Caching\n- Rate limiting\n- Session management\n\n### Containment Strategies\n\n**Command-Query Separation:**\n```python\n# Query: No side effects\ndef get_order_total(order): -> Decimal\n\n# Command: Mutations allowed\ndef place_order(order) -> None\n```\n\n**Effect Tracking:**\n```python\n# Explicit effect types\nEffect = Database | API | Cache | Event\n\ndef process_payment(order) -> tuple[Result, list[Effect]]:\n    effects = []\n    # Track all effects\n    return result, effects\n```\n\n## Cross-Boundary Dependencies\n\n### Allowed Patterns\n\n**1. Events:**\n```python\n# Service A publishes\nevent_bus.publish(UserCreated(user_id))\n\n# Service B subscribes\n@subscribe(UserCreated)\ndef handle_user_created(event):\n    # React independently\n```\n\n**2. Shared Kernel:**\n```python\n# Common domain types\nfrom shared.types import Money, UserId, Email\n```\n\n**3. Published APIs:**\n```python\n# Service B calls Service A's API\nresponse = service_a_client.get_user(user_id)\n```\n\n### Forbidden Patterns\n\n**1. Shared Database:**\n```python\n# Bad: Direct database access across services\nuser_db.query(\"SELECT * FROM users\")  # From order service\n```\n\n**2. Implementation Sharing:**\n```python\n# Bad: Importing internal modules\nfrom service_a.internal.helpers import format_date\n```\n\n## Integration with Architecture Review\n\nUse this module during Step 3 (Interaction Mapping):\n1. Map all module interactions (before/after)\n2. Verify composition boundaries\n3. Check data ownership clarity\n4. Validate dependency flow direction\n5. Detect circular dependencies\n6. Identify coupling violations\n7. Analyze side effect containment\n\nFile v1.9.19:modules/fpf-methodology.md\n\n# FPF Architecture Review Methodology\n\nConduct architecture reviews using the FPF (Functional, Practical, Foundation) methodology, evaluating codebases through three complementary perspectives.\n\n## Philosophy\n\nArchitecture reviews should be systematic and multi-dimensional. FPF provides three lenses:\n- **Functional**: What the system does (capabilities, behaviors)\n- **Practical**: How well it works (performance, usability)\n- **Foundation**: What it's built on (principles, patterns)\n\n## Quick Start\n\n```bash\n# Full FPF review\n/architecture-review --methodology fpf\n\n# Specific perspective\n/architecture-review --perspective functional\n/architecture-review --perspective practical\n/architecture-review --perspective foundation\n```\n\n## The Three Perspectives\n\n### 1. Functional Perspective\n\n**Question:** What does this system do?\n\n**Evaluates:**\n- Feature completeness\n- Capability coverage\n- Behavior correctness\n- Integration points\n\n**Outputs:**\n- Feature inventory\n- Capability gaps\n- Behavior anomalies\n\n### 2. Practical Perspective\n\n**Question:** How well does this system work?\n\n**Evaluates:**\n- Performance characteristics\n- Usability patterns\n- Operational concerns\n- Scalability considerations\n\n**Outputs:**\n- Performance assessment\n- Usability issues\n- Operational recommendations\n\n### 3. Foundation Perspective\n\n**Question:** What is this system built on?\n\n**Evaluates:**\n- Architectural patterns\n- Design principles\n- Code quality\n- Technical debt\n\n**Outputs:**\n- Pattern analysis\n- Principle adherence\n- Debt inventory\n\n## FPF Workflow\n\n### Phase 1: Discovery\n1. Scan codebase structure - Identify components, modules, layers\n2. Map dependencies - Internal and external relationships\n3. Identify entry points - Public APIs, commands, interfaces\n\n### Phase 2: Functional Analysis\n1. Inventory features - What capabilities exist\n2. Trace behaviors - How features work end-to-end\n3. Identify gaps - Missing or incomplete functionality\n\n### Phase 3: Practical Analysis\n1. Assess performance - Latency, throughput, resource usage\n2. Evaluate usability - Developer experience, API design\n3. Check operations - Logging, monitoring, error handling\n\n### Phase 4: Foundation Analysis\n1. Pattern recognition - What patterns are used\n2. Principle check - SOLID, DRY, KISS adherence\n3. Debt assessment - Technical debt inventory\n\n### Phase 5: Synthesis\n1. Cross-reference findings - Connect issues across perspectives\n2. Prioritize recommendations - Based on impact and effort\n3. Generate report - Structured findings and actions\n\n## FPF Report Template\n\n```markdown\n# FPF Architecture Review: [Project/Component]\n\n**Date:** [DATE]\n**Scope:** [what was reviewed]\n\n## Executive Summary\n[2-3 sentence overview of findings]\n\n## Functional Perspective\n### Features Inventory\n| Feature | Status | Notes |\n|---------|--------|-------|\n| [Feature 1] | Complete | - |\n\n### Capability Gaps\n1. [Gap 1] - [Impact]\n\n## Practical Perspective\n### Performance Assessment\n| Metric | Current | Target | Status |\n|--------|---------|--------|--------|\n| [Metric 1] | [value] | [target] | PASS/FAIL |\n\n## Foundation Perspective\n### Pattern Analysis\n| Pattern | Usage | Assessment |\n|---------|-------|------------|\n| [Pattern 1] | [where used] | Appropriate/Problematic |\n\n### Technical Debt\n| Item | Severity | Effort | Priority |\n|------|----------|--------|----------|\n| [Debt 1] | High | Medium | P1 |\n\n## Recommendations\n### High Priority\n1. **[Recommendation]** - Impact: [what improves] - Effort: [estimate]\n```\n\n## Configuration\n\n```yaml\nperspectives:\n  functional:\n    enabled: true\n    depth: \"full\"  # full, summary\n  practical:\n    enabled: true\n    depth: \"full\"\n  foundation:\n    enabled: true\n    depth: \"full\"\n```\n\n## Guardrails\n\n1. **Scope boundaries** - Stay within configured scope\n2. **Evidence-based** - Every finding needs supporting evidence\n3. **Actionable output** - Recommendations must be actionable\n4. **Balanced perspectives** - Don't over-index on one perspective\n\n## References\n\n- [FPF Framework](https://github.com/ailev/FPF) - Original methodology\n- [quint-code](https://github.com/m0n0x41d/quint-code) - Heavy implementation (this skill is lighter)\n\nFile v1.9.19:modules/principle-checks.md\n\n---\nname: principle-checks\ndescription: Law of Demeter, anti-slop patterns, AI guardrails, and security/performance checks\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [principles, demeter, anti-patterns, security, performance, quality]\ncomplexity: advanced\nestimated_tokens: 500\n---\n\n# Principle Checks Module\n\nSystematic verification of architectural principles, anti-patterns, and quality attributes.\n\n## Law of Demeter (LoD)\n\n### The Principle\n\n\"Talk to friends, not to strangers.\"\n\nAn object should only call methods on:\n1. Itself\n2. Its parameters\n3. Objects it creates\n4. Its direct components\n\n### Train Wreck Detection\n\n**Anti-pattern:**\n```python\n# Bad: Chain of calls\ncustomer.get_address().get_city().get_postal_code()\n\n# Bad: Multiple dereferences\norder.customer.billing_address.street\n\n# Bad: Deep navigation\ncontext.request.session.user.preferences.theme\n```\n\n**Search patterns:**\n```bash\n# Python\ngrep -rn '\\.\\w\\+(\\)\\.\\w\\+(\\)\\.\\w\\+(' src/\n\n# JavaScript/TypeScript\ngrep -rn '\\.\\w\\+\\.\\w\\+\\.\\w\\+' src/ --include=\"*.js\" --include=\"*.ts\"\n\n# Count violations\ngrep -r '\\.\\w\\+\\.\\w\\+\\.\\w\\+' src/ | wc -l\n```\n\n### Refactoring Strategies\n\n**Strategy 1: Tell, Don't Ask**\n```python\n# Before\nif customer.get_address().get_country() == \"US\":\n    apply_us_tax()\n\n# After\nif customer.is_in_country(\"US\"):\n    apply_us_tax()\n```\n\n**Strategy 2: Move Logic to Owner**\n```python\n# Before\npostal_code = customer.get_address().get_postal_code()\nregion = lookup_region(postal_code)\n\n# After\nregion = customer.get_region()  # Address logic inside Customer\n```\n\n**Strategy 3: Introduce Facade**\n```python\n# Before\nconfig.get_database().get_connection_pool().get_connection()\n\n# After\nconfig.get_database_connection()  # Facade hides complexity\n```\n\n## Anti-Slop Checks\n\n### What is \"Slop\"?\n\nCode that appears professional but lacks substance:\n- Generic naming\n- Overengineering\n- Cargo cult patterns\n- Hallucinated dependencies\n- Hollow abstractions\n\n### Detection Patterns\n\n**1. Overengineering Red Flags:**\n```python\n# Bad: Unnecessary abstraction layers\nclass UserFactoryFactory:\n    def create_user_factory(self):\n        return UserFactory()\n\n# Bad: Premature generalization\nclass AbstractBaseEntityManagerInterface:\n    pass\n```\n\n**Search:**\n```bash\n# Find \"Abstract\" overuse\ngrep -r \"class Abstract\" src/ | wc -l\n\n# Find \"Manager\" bloat\ngrep -r \"Manager\\|Handler\\|Processor\" src/ --include=\"*.py\"\n\n# Find deep inheritance\ngrep -A 5 \"class.*:\" src/**/*.py | grep \"    class\"\n```\n\n**2. Generic Naming:**\n```python\n# Bad: Non-descriptive names\ndef process_data(data):\n    result = handle_item(data)\n    return do_thing(result)\n\n# Good: Specific names\ndef calculate_tax(order):\n    taxable_amount = extract_taxable_items(order)\n    return apply_tax_rate(taxable_amount)\n```\n\n**Search:**\n```bash\n# Find generic names\ngrep -rn \"process\\|handle\\|manage\\|do_\\|data\\|item\\|thing\" src/\n```\n\n**3. Hidden Fragility:**\n```python\n# Bad: Silent failure\ntry:\n    critical_operation()\nexcept Exception:\n    pass  # Swallowed error\n\n# Bad: Implicit coupling\nglobal_state = {}  # Hidden dependency\n\n# Bad: Magic values\nif status == 42:  # What does 42 mean?\n```\n\n**Search:**\n```bash\n# Find bare except\ngrep -rn \"except:\" src/\n\n# Find global state\ngrep -rn \"^[A-Z_]\\+ = \" src/\n\n# Find magic numbers\ngrep -rn \"if.*== [0-9]\\+\" src/\n```\n\n**4. Hallucinated Dependencies:**\n```python\n# Bad: Assuming non-existent methods\nuser.auto_validate()  # Does this exist?\ncache.smart_invalidate()  # What does \"smart\" mean?\n\n# Bad: Imaginary patterns\n@auto_retry  # Not in codebase\n@cache_result  # Decorator doesn't exist\n```\n\n**Verification:**\n```bash\n# Check decorator existence\ngrep -r \"^def auto_retry\\|^class auto_retry\" src/\n\n# Verify method definitions\ngrep -r \"def auto_validate\" src/\n```\n\n## Guardrails for AI Assistance\n\n### Evidence-Based Critiques\n\n**Required:**\n- File paths\n- Line numbers\n- Actual code snippets\n- Measured metrics\n\n**Forbidden:**\n- \"Looks like...\"\n- \"Probably should...\"\n- \"Best practice is...\"\n- \"Generally we...\"\n\n### Trade-Off Statements\n\n**Good:**\n```\nOption A: PostgreSQL\n+ Proven reliability, ACID compliance\n+ Team expertise\n- Higher hosting cost\n- Vertical scaling limits\n\nOption B: DynamoDB\n+ Horizontal scalability\n+ Lower latency\n- Team learning curve\n- Complex query limitations\n```\n\n**Bad:**\n```\n\"PostgreSQL is better for this use case.\"\n\"DynamoDB would be more scalable.\"\n```\n\n### Replace Hollow Phrases\n\n| Hollow Phrase | Replace With |\n|--------------|--------------|\n| \"Clean code\" | Specific principle (SRP, LoD) |\n| \"Best practice\" | Cited guideline or measured benefit |\n| \"Should be\" | Evidence-based observation |\n| \"More maintainable\" | Specific metric (coupling, complexity) |\n| \"Industry standard\" | Named standard (RESTful, OAuth 2.0) |\n\n## Security Checks\n\n### Input Validation\n\n**1. Boundary Validation:**\n```python\n# Check: All external inputs validated\n@validate_input\ndef create_user(email: str, age: int):\n    if not is_valid_email(email):\n        raise ValidationError(\"Invalid email\")\n    if not (0 < age < 150):\n        raise ValidationError(\"Invalid age\")\n```\n\n**Search:**\n```bash\n# Find unvalidated endpoints\ngrep -rn \"@app.route\\|@api\" src/ -A 10 | grep -v \"validate\\|check\\|verify\"\n```\n\n**2. SQL Injection Prevention:**\n```python\n# Bad\nquery = f\"SELECT * FROM users WHERE id = {user_id}\"\n\n# Good\nquery = \"SELECT * FROM users WHERE id = ?\"\ncursor.execute(query, (user_id,))\n```\n\n**Search:**\n```bash\n# Find string interpolation in SQL\ngrep -rn \"f\\\".*SELECT\\|\\\".*SELECT.*{\" src/\n```\n\n**3. XSS Prevention:**\n```python\n# Check for auto-escaping\n# Framework default: Flask (manual), Django (auto)\n```\n\n### Least Privilege\n\n**1. Minimum Permissions:**\n```python\n# Bad: Admin for everything\ndb_user = \"admin\"\n\n# Good: Specific roles\ndb_user = \"app_readonly\"  # For queries\ndb_user = \"app_writer\"    # For mutations\n```\n\n**2. Capability Checks:**\n```bash\n# Find permission checks\ngrep -rn \"check_permission\\|require_role\\|authorize\" src/\n```\n\n### Error Handling\n\n**1. No Sensitive Leaks:**\n```python\n# Bad\nexcept Exception as e:\n    return {\"error\": str(e)}  # May expose internals\n\n# Good\nexcept Exception as e:\n    logger.error(f\"Operation failed: {e}\")\n    return {\"error\": \"Operation failed\"}\n```\n\n**2. Proper Logging:**\n```bash\n# Check logging coverage\ngrep -rn \"logger\\.\\(error\\|warning\\)\" src/ | wc -l\n```\n\n## Performance Checks\n\n### Performance Budgets\n\nDefine limits:\n```yaml\nresponse_time:\n  p50: 100ms\n  p95: 500ms\n  p99: 1000ms\n\ndatabase_queries:\n  max_per_request: 10\n\nmemory:\n  max_heap: 512MB\n```\n\n### N+1 Query Detection\n\n```python\n# Bad: N+1 queries\nfor user in users:\n    user.get_orders()  # Query per user\n\n# Good: Eager loading\nusers = User.query.options(joinedload('orders')).all()\n```\n\n**Search:**\n```bash\n# Find potential N+1\ngrep -rn \"for.*in.*:\" src/ -A 3 | grep \"get_\\|fetch_\\|find_\"\n```\n\n### Caching Strategy\n\n**Check for:**\n- Cache key design\n- TTL configuration\n- Invalidation strategy\n- Cache stampede prevention\n\n```bash\n# Find caching usage\ngrep -rn \"@cache\\|cache.get\\|cache.set\" src/\n```\n\n### Index Coverage\n\n```bash\n# Check migrations for indexes\ngrep -r \"CREATE INDEX\\|add_index\" migrations/\n\n# Find missing indexes (slow queries)\n# Review query logs, not static analysis\n```\n\n## Integration with Architecture Review\n\nUse this module during Step 4 (Principle Checks):\n1. Run LoD detection searches\n2. Check for anti-slop patterns\n3. Verify AI assistance guardrails\n4. Execute security checks\n5. Validate performance budgets\n6. Document violations with evidence\n7. Recommend specific fixes with file/line references\n\nFile v1.9.19:skill-card.md\n\n## Description:\n\nAssesses architecture decisions, ADR compliance, and coupling.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[athola](https://clawhub.ai/user/athola)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use this skill to review architecture changes, ADR compliance, module coupling, invariants, and design-principle risks before merging significant structural work.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill is expected to read and search the active repository during architecture review.\n\nMitigation: Use it on intended repositories and scopes, and narrow local triggers if generic design discussions should not load the workflow.\n\nRisk: Architecture recommendations may be incomplete or incorrect when the change conflicts with existing design invariants.\n\nMitigation: Escalate invariant conflicts to human judgment and present preserve, layer, and revise options before acting on a recommendation.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/athola/skills/nm-pensive-architecture-review)\n- [Pensive Plugin Homepage](https://github.com/athola/claude-night-market/tree/master/plugins/pensive)\n- [FPF Framework](https://github.com/ailev/FPF)\n- [quint-code](https://github.com/m0n0x41d/quint-code)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, guidance]\n\n**Output Format:** [Markdown review guidance with checklists, evidence-backed findings, diagrams, and inline shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include approve, approve-with-actions, or block recommendations and follow-up actions.]\n\n## Skill Version(s):\n\n1.9.19 (source: release metadata; artifact frontmatter lists 1.9.8)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.9.17: 7 files, 15286 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), skill-card.md (2241b), SKILL.md (7846b), _meta.json (150b)\n\nFile v1.9.17:SKILL.md\n\n---\nname: architecture-review\ndescription: Assesses architecture decisions, ADR compliance, and coupling\nversion: 1.9.8\ntriggers:\n  - architecture\n  - design\n  - adr\n  - coupling\n  - patterns\n  - principles\n  - evaluating design changes or validating structural decisions before merging\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/athola/claude-night-market/tree/master/plugins/pensive\", \"emoji\": \"\\ud83c\\udfd7\\ufe0f\", \"requires\": {\"config\": [\"night-market.pensive:shared\", \"night-market.imbue:proof-of-work\", \"night-market.imbue:diff-analysis/modules/risk-assessment-framework\"]}}}\nsource: claude-night-market\nsource_plugin: pensive\n---\n\n> **Night Market Skill** — ported from [claude-night-market/pensive](https://github.com/athola/claude-night-market/tree/master/plugins/pensive). For the full experience with agents, hooks, and commands, install the Claude Code plugin.\n\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [When to Use](#when-to-use)\n- [Progressive Loading](#progressive-loading)\n- [Required TodoWrite Items](#required-todowrite-items)\n- [Workflow](#workflow)\n- [Step 1: Establish Context (`arch-review:context-established`)](#step-1:-establish-context-(arch-review:context-established))\n- [Step 2: ADR Audit (`arch-review:adr-audit`)](#step-2:-adr-audit-(arch-review:adr-audit))\n- [Step 3: Interaction Mapping (`arch-review:interaction-mapping`)](#step-3:-interaction-mapping-(arch-review:interaction-mapping))\n- [Step 4: Principle Checks (`arch-review:principle-checks`)](#step-4:-principle-checks-(arch-review:principle-checks))\n- [Step 5: Risks and Actions (`arch-review:risks-actions`)](#step-5:-risks-and-actions-(arch-review:risks-actions))\n- [Testing](#testing)\n\n## Testing\n\nRun `pytest plugins/pensive/tests/skills/test_architecture_review.py` to verify review logic.\n- [Architecture Principles Checklist](#architecture-principles-checklist)\n- [Coupling](#coupling)\n- [Cohesion](#cohesion)\n- [Layering](#layering)\n- [Evolution](#evolution)\n\n\n# Architecture Review Workflow\n\nArchitecture assessment against ADRs and design principles.\n\n## Quick Start\n\n```bash\n/architecture-review\n```\n\n## When To Use\n\n- Approving reimplementations.\n- Large-scale refactoring reviews.\n- System design changes.\n- New module/service introduction.\n- Dependency restructuring.\n\n## When NOT To Use\n\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n\n## Progressive Loading\n\nLoad modules based on review scope:\n\n- **`modules/adr-audit.md`** (~400 tokens): ADR verification and documentation.\n- **`modules/coupling-analysis.md`** (~450 tokens): Dependency analysis and boundary violations.\n- **`modules/principle-checks.md`** (~500 tokens): Code quality, security, and performance.\n- **`modules/fpf-methodology.md`** (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.\n\nLoad all modules for full reviews. For focused reviews, load only relevant modules.\n\n## Required TodoWrite Items\n\n1. `arch-review:context-established`: Repository, branch, motivation.\n2. `arch-review:adr-audit`: ADR verification and new ADR needs.\n3. `arch-review:interaction-mapping`: Module coupling analysis.\n4. `arch-review:invariant-check`: Invariant conflict detection and 3-option analysis.\n5. `arch-review:principle-checks`: LoD, security, performance.\n6. `arch-review:risks-actions`: Recommendation and follow-ups.\n\n## Workflow\n\n### Step 1: Establish Context (`arch-review:context-established`)\n\nConfirm repository and branch:\n```bash\npwd\ngit status -sb\n```\n\nDocument:\n- Feature/bug/epic motivating review.\n- Affected subsystems.\n- Architectural intent from README/docs.\n- Design trade-off assumptions.\n\n### Step 2: ADR Audit (`arch-review:adr-audit`)\n\n**Load: `modules/adr-audit.md`**\n\n- Locate ADRs in project.\n- Verify required sections.\n- Check status flow.\n- Confirm immutability compliance.\n- Flag need for new ADRs.\n\n### Step 3: Interaction Mapping (`arch-review:interaction-mapping`)\n\n**Load: `modules/coupling-analysis.md`**\n\n- Diagram before/after module interactions.\n- Verify composition boundaries.\n- Check data ownership clarity.\n- Validate dependency flow direction.\n- Identify coupling violations.\n\n### Step 3.5: Invariant Conflict Detection (`arch-review:invariant-check`)\n\nBefore checking principles, identify whether the changes\nconflict with existing design invariants. This is the\nhighest-judgment step in architecture review — models\nget this wrong more often than any other call.\n\n**Identify existing invariants:**\n\n1. Scan ADRs for recorded decisions still in \"accepted\"\n   status\n2. Check module boundaries (are imports crossing layers\n   that previously didn't?)\n3. Check data flow direction (does data now flow in a\n   new direction?)\n4. Check API contracts (are public interfaces changing\n   shape?)\n5. Check structural patterns (is a new pattern being\n   introduced alongside an existing one?)\n\n```bash\n# Detect boundary crossings in changed files\ngit diff --name-only | while read f; do\n  head -20 \"$f\" 2>/dev/null | rg \"^(import|from|use |require)\" || true\ndone\n```\n\n**When a conflict is detected:**\n\nDo NOT recommend a resolution. Present the three options\nand escalate to human judgment:\n\n| Option | When Right | When Wrong |\n|--------|------------|------------|\n| **Preserve invariant** (reject feature) | Invariant simplifies many things; feature is marginal | Feature is genuinely needed and invariant is stale |\n| **Layer on top** (add inelegantly) | Feature is needed; invariant still valuable; imperfection is OK | Layering creates a maintenance trap that will compound |\n| **Revise invariant** (change the design) | Genuine new learning invalidates the original reasoning | You're \"cleaning up\" a decision you don't fully understand |\n\n**Output format:**\n\n```markdown\n### Invariant Conflicts\n\n[I1] **[Invariant name]** — [what decision it represents]\n- **Conflict**: [what change clashes]\n- **Options**: Preserve / Layer / Revise\n- **Recommendation**: ESCALATE TO HUMAN\n- **Risk if wrong**: [what compounds]\n```\n\n**Why this matters:** Bad invariant decisions compound.\nAfter a few wrong calls the codebase becomes\nunsalvageable. This is a judgment problem, not a context\nproblem — the agent should surface it, not solve it.\n\n### Step 4: Principle Checks (`arch-review:principle-checks`)\n\n**Load: `modules/principle-checks.md`**\n\n- Law of Demeter.\n- Anti-slop patterns.\n- Security (input validation, least privilege).\n- Performance (N+1 queries, caching).\n\n### Step 5: Risks and Actions (`arch-review:risks-actions`)\n\nSummarize using `imbue:diff-analysis/modules/risk-assessment-framework`:\n- Current vs proposed architecture.\n- Business impact.\n- Technical debt implications.\n\nList follow-ups with owners and dates.\n\nProvide recommendation:\n- **Approve**: Architecture sound.\n- **Approve with actions**: Minor issues to address.\n- **Block**: Fundamental problems requiring redesign.\n\n## Architecture Principles Checklist\n\n### Coupling\n- [ ] Dependencies follow defined boundaries.\n- [ ] No circular dependencies.\n- [ ] Extension points used properly.\n- [ ] Abstractions don't leak.\n\n### Cohesion\n- [ ] Related functionality grouped.\n- [ ] Single responsibility per module.\n- [ ] Clear module purposes.\n\n### Layering\n- [ ] Layers have clear responsibilities.\n- [ ] Dependencies flow downward.\n- [ ] No layer bypassing.\n\n### Invariants\n- [ ] Existing design invariants identified.\n- [ ] Conflicts between changes and invariants surfaced.\n- [ ] Three-option analysis (preserve/layer/revise) presented.\n- [ ] Invariant changes escalated to human judgment.\n- [ ] No silent invariant revisions in the diff.\n\n### Evolution\n- [ ] Changes are reversible.\n- [ ] Migration paths are clear.\n- [ ] ADRs document decisions.\n\nFile v1.9.17:_meta.json\n\n{\n  \"ownerId\": \"kn7d107jg9jv602h9ytsegydq184a42s\",\n  \"slug\": \"nm-pensive-architecture-review\",\n  \"version\": \"1.9.17\",\n  \"publishedAt\": 1785389918297\n}\n\nFile v1.9.17:modules/adr-audit.md\n\n---\nname: adr-audit\ndescription: Architecture Decision Record audit patterns and verification workflows\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [adr, documentation, governance, decisions]\ncomplexity: intermediate\nestimated_tokens: 400\n---\n\n# ADR Audit Module\n\ndetailed ADR discovery, validation, and governance patterns.\n\n## ADR Location Patterns\n\nCommon ADR locations by project type:\n\n```bash\n# Standard locations\nwiki/architecture/\ndocs/adr/\ndocs/decisions/\narchitecture/decisions/\n.adr/\n\n# Search pattern\nfind . -type f -name \"*ADR*\" -o -name \"*decision*\" | grep -E \"\\.(md|txt)$\"\n```\n\n## Required ADR Sections\n\nEvery ADR must include:\n\n### 1. Title\nClear, specific decision statement:\n- \"Use PostgreSQL for primary datastore\"\n- \"Adopt hexagonal architecture pattern\"\n- \"Implement JWT-based authentication\"\n\n### 2. Status\nMust follow strict progression:\n```\nProposed → Reviewed → Accepted\n                    ↓\n              Superseded (when invalidated)\n```\n\n**Rules:**\n- Status changes are append-only\n- Date each status transition\n- Never delete/modify accepted ADRs\n- Use \"Superseded by ADR-XXX\" to replace\n\n### 3. Context\nDocument the forces at play:\n- Business requirements\n- Technical constraints\n- Team capabilities\n- Timeline pressures\n- Existing architecture\n\n### 4. Decision\nThe \"we will...\" statement:\n- Clear action chosen\n- Implementation approach\n- Key design choices\n\n### 5. Alternatives Considered\nFor each alternative:\n- Description\n- Pros/cons\n- Why rejected\n\nMinimum 2 alternatives required.\n\n### 6. Consequences\n\n**Positive:**\n- Benefits gained\n- Problems solved\n- Capabilities enabled\n\n**Negative:**\n- Trade-offs accepted\n- Technical debt incurred\n- Complexity added\n\n**Neutral:**\n- Changes required\n- Migration steps\n- Training needs\n\n### 7. Metadata\n```yaml\nDate: YYYY-MM-DD\nAuthor: [name]\nStatus: [status]\nSupersedes: [ADR-XXX] (if applicable)\nSuperseded-by: [ADR-XXX] (if applicable)\n```\n\n## Status Flow Verification\n\n### Valid Transitions\n- Proposed → Reviewed\n- Reviewed → Accepted\n- Reviewed → Rejected\n- Accepted → Superseded (via new ADR only)\n\n### Invalid Transitions\n- Proposed -> Accepted (skip review)\n- Accepted -> Rejected (use Superseded)\n- Superseded -> Accepted (immutable)\n\n## Immutability Rules\n\n**Once Accepted:**\n1. **Never modify** decision content\n2. **Never change** consequences\n3. **Never delete** the ADR\n4. **Only append** status changes\n\n**To Replace:**\n1. Create new ADR with superseding decision\n2. Add \"Supersedes: ADR-XXX\" to new ADR\n3. Add \"Superseded-by: ADR-YYY\" to old ADR\n4. Update old ADR status to \"Superseded\"\n\n## Audit Workflow\n\n### 1. Locate All ADRs\n```bash\n# Find ADR directory\nls -la docs/adr/ wiki/architecture/ 2>/dev/null\n\n# Count ADRs\nfind . -path \"*/adr/*.md\" -o -path \"*/decisions/*.md\" | wc -l\n```\n\n### 2. Verify Structure\nFor each ADR:\n- [ ] Has all required sections\n- [ ] Status follows valid flow\n- [ ] Dates are present\n- [ ] Alternatives documented (≥2)\n- [ ] Consequences specified\n\n### 3. Check References\n```bash\n# Find ADR references in code\ngrep -r \"ADR-[0-9]\" --include=\"*.md\" --include=\"*.py\" --include=\"*.js\"\n\n# Verify backlinks\ngrep \"Superseded-by\" docs/adr/*.md\n```\n\n### 4. Flag Issues\nCommon problems:\n- Missing sections\n- Invalid status transitions\n- Modified accepted ADRs\n- Missing supersession links\n- Insufficient alternatives\n\n## New ADR Requirements\n\nFlag need for new ADR when:\n- Introducing new architectural pattern\n- Changing core technology\n- Modifying system boundaries\n- Adding external dependencies\n- Changing security model\n\n**Before implementation:**\n1. Draft ADR with all sections\n2. Set status: Proposed\n3. Request review\n4. Update to Reviewed\n5. Gain approval → Accepted\n6. Then proceed with implementation\n\n## Integration with Architecture Review\n\nUse this module during Step 2 (ADR Audit):\n1. Locate ADRs using patterns\n2. Verify structure completeness\n3. Check status flow validity\n4. Confirm immutability compliance\n5. Identify missing ADRs for current work\n6. Draft new ADRs if needed\n\nFile v1.9.17:modules/coupling-analysis.md\n\n---\nname: coupling-analysis\ndescription: Interaction mapping, composition boundaries, and dependency flow analysis\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [coupling, dependencies, composition, boundaries, modularity]\ncomplexity: advanced\nestimated_tokens: 450\n---\n\n# Coupling Analysis Module\n\nSystematic analysis of module interactions, boundaries, and dependency flows.\n\n## Interaction Mapping Patterns\n\n### Visual Representation\n\nCreate before/after diagrams:\n\n```\nBefore:\n┌─────────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│Module B │────▶│ Database │\n└─────────┘     └─────────┘     └──────────┘\n\nAfter:\n┌─────────┐     ┌───────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│ Cache │────▶│Module B │────▶│ Database │\n└─────────┘     └───────┘     └─────────┘     └──────────┘\n```\n\n### Dependency Graph Tools\n\n```bash\n# Python: Generate import graph\npydeps --max-bacon=2 --cluster src/\n\n# TypeScript: Analyze module dependencies\nmadge --circular --extensions ts src/\n\n# Generic: Find direct dependencies\ngrep -r \"import\\|require\\|from\" src/ | cut -d: -f1 | sort | uniq -c\n```\n\n## Composition Boundaries\n\n### Boundary Definition\n\nClear boundaries have:\n1. **Explicit interfaces** - Published contracts\n2. **Data ownership** - Single source of truth\n3. **Encapsulation** - Hidden implementation\n4. **Stability** - Minimal breaking changes\n\n### Boundary Types\n\n**Module Boundaries:**\n```\n┌──────────────────────────┐\n│   Public API             │\n├──────────────────────────┤\n│   Internal Logic         │\n│   (implementation)       │\n└──────────────────────────┘\n```\n\n**Layer Boundaries:**\n```\n┌──────────────────────────┐\n│   Presentation Layer     │ ← HTTP/UI\n├──────────────────────────┤\n│   Application Layer      │ ← Business Logic\n├──────────────────────────┤\n│   Domain Layer           │ ← Core Models\n├──────────────────────────┤\n│   Infrastructure Layer   │ ← Database/External\n└──────────────────────────┘\n```\n\n**Service Boundaries:**\n```\nService A          Service B\n┌────────┐        ┌────────┐\n│  API   │◀──────▶│  API   │\n├────────┤        ├────────┤\n│  DB A  │        │  DB B  │\n└────────┘        └────────┘\n```\n\n### Boundary Violations\n\n**Ad-hoc Reach-ins:**\n```python\n# Bad: Reaching through module boundary\nuser.profile.settings.theme.get_color()\n\n# Good: Ask for what you need\nuser.get_theme_color()\n```\n\n**Layering Violations:**\n```python\n# Bad: Domain layer accessing infrastructure\nclass Order:\n    def save(self):\n        db.execute(\"INSERT INTO orders...\")\n\n# Good: Infrastructure handles persistence\nclass OrderRepository:\n    def save(self, order: Order):\n        db.execute(\"INSERT INTO orders...\")\n```\n\n## Data Ownership Analysis\n\n### Single Owner Principle\n\nEach data entity has exactly one authoritative owner:\n\n```\nUser Data:\n├── Auth Service (owner: credentials)\n├── Profile Service (owner: profile data)\n└── Analytics Service (consumer: read-only)\n```\n\n### Ownership Violations\n\n**Multiple Writers:**\n```python\n# Bad: Two services modify same data\nauth_service.update_user_email()\nprofile_service.update_user_email()\n\n# Good: Single owner\nprofile_service.update_email()  # Publishes event\nauth_service.handle_email_changed()  # Subscribes to event\n```\n\n**Ownership Leaks:**\n```python\n# Bad: Exposing internal structure\ndef get_user():\n    return user_database_model\n\n# Good: Return boundary type\ndef get_user():\n    return UserDTO(id=..., name=...)\n```\n\n## Dependency Flow Checking\n\n### Expected Flow Patterns\n\n**Layered Architecture:**\n```\nPresentation → Application → Domain → Infrastructure\n     ↓              ↓           ↓            ↓\n  (no reverse dependencies allowed)\n```\n\n**Hexagonal Architecture:**\n```\n     ┌─────────────┐\n     │   Domain    │ ← Core (no dependencies)\n     └──────┬──────┘\n            │\n  ┌─────────┴─────────┐\n  │   Application     │ ← Orchestration\n  └────────┬──────────┘\n           │\n  ┌────────┴─────────┐\n  │   Adapters       │ ← External interfaces\n  └──────────────────┘\n```\n\n### Circular Dependency Detection\n\n```bash\n# Python\npydeps --show-cycles src/\n\n# JavaScript/TypeScript\nmadge --circular src/\n\n# Manual check\ngrep -r \"from.*import\" src/ | # Extract all imports\n  python -c \"\nimport sys\nfrom collections import defaultdict\n\ngraph = defaultdict(set)\nfor line in sys.stdin:\n    # Parse: file imports module\n    # Build graph, detect cycles\n\"\n```\n\n### Dependency Metrics\n\n**Afferent Coupling (Ca):**\nNumber of modules that depend on this module.\n- High Ca = Stable (many dependents)\n\n**Efferent Coupling (Ce):**\nNumber of modules this module depends on.\n- High Ce = Unstable (many dependencies)\n\n**Instability (I):**\n```\nI = Ce / (Ca + Ce)\n```\n- I = 0: Maximally stable\n- I = 1: Maximally unstable\n\n### Ideal Patterns\n\n**Stable Abstractions:**\n- Core domain: Low I (stable)\n- Infrastructure: High I (unstable, replaceable)\n\n**Dependency Direction:**\n```\nUnstable → Stable\n(changing) depends on (stable)\n```\n\n## Side Effects Analysis\n\n### Side Effect Categories\n\n**1. State Mutations:**\n```python\n# Track mutations\ndef process_order(order):\n    order.status = \"PROCESSED\"  # Mutation\n    notify_customer(order)       # Side effect\n    log_event(order)            # Side effect\n```\n\n**2. External I/O:**\n- Database writes\n- API calls\n- File operations\n- Message queue publishing\n\n**3. Timing Dependencies:**\n- Caching\n- Rate limiting\n- Session management\n\n### Containment Strategies\n\n**Command-Query Separation:**\n```python\n# Query: No side effects\ndef get_order_total(order): -> Decimal\n\n# Command: Mutations allowed\ndef place_order(order) -> None\n```\n\n**Effect Tracking:**\n```python\n# Explicit effect types\nEffect = Database | API | Cache | Event\n\ndef process_payment(order) -> tuple[Result, list[Effect]]:\n    effects = []\n    # Track all effects\n    return result, effects\n```\n\n## Cross-Boundary Dependencies\n\n### Allowed Patterns\n\n**1. Events:**\n```python\n# Service A publishes\nevent_bus.publish(UserCreated(user_id))\n\n# Service B subscribes\n@subscribe(UserCreated)\ndef handle_user_created(event):\n    # React independently\n```\n\n**2. Shared Kernel:**\n```python\n# Common domain types\nfrom shared.types import Money, UserId, Email\n```\n\n**3. Published APIs:**\n```python\n# Service B calls Service A's API\nresponse = service_a_client.get_user(user_id)\n```\n\n### Forbidden Patterns\n\n**1. Shared Database:**\n```python\n# Bad: Direct database access across services\nuser_db.query(\"SELECT * FROM users\")  # From order service\n```\n\n**2. Implementation Sharing:**\n```python\n# Bad: Importing internal modules\nfrom service_a.internal.helpers import format_date\n```\n\n## Integration with Architecture Review\n\nUse this module during Step 3 (Interaction Mapping):\n1. Map all module interactions (before/after)\n2. Verify composition boundaries\n3. Check data ownership clarity\n4. Validate dependency flow direction\n5. Detect circular dependencies\n6. Identify coupling violations\n7. Analyze side effect containment\n\nFile v1.9.17:modules/fpf-methodology.md\n\n# FPF Architecture Review Methodology\n\nConduct architecture reviews using the FPF (Functional, Practical, Foundation) methodology, evaluating codebases through three complementary perspectives.\n\n## Philosophy\n\nArchitecture reviews should be systematic and multi-dimensional. FPF provides three lenses:\n- **Functional**: What the system does (capabilities, behaviors)\n- **Practical**: How well it works (performance, usability)\n- **Foundation**: What it's built on (principles, patterns)\n\n## Quick Start\n\n```bash\n# Full FPF review\n/architecture-review --methodology fpf\n\n# Specific perspective\n/architecture-review --perspective functional\n/architecture-review --perspective practical\n/architecture-review --perspective foundation\n```\n\n## The Three Perspectives\n\n### 1. Functional Perspective\n\n**Question:** What does this system do?\n\n**Evaluates:**\n- Feature completeness\n- Capability coverage\n- Behavior correctness\n- Integration points\n\n**Outputs:**\n- Feature inventory\n- Capability gaps\n- Behavior anomalies\n\n### 2. Practical Perspective\n\n**Question:** How well does this system work?\n\n**Evaluates:**\n- Performance characteristics\n- Usability patterns\n- Operational concerns\n- Scalability considerations\n\n**Outputs:**\n- Performance assessment\n- Usability issues\n- Operational recommendations\n\n### 3. Foundation Perspective\n\n**Question:** What is this system built on?\n\n**Evaluates:**\n- Architectural patterns\n- Design principles\n- Code quality\n- Technical debt\n\n**Outputs:**\n- Pattern analysis\n- Principle adherence\n- Debt inventory\n\n## FPF Workflow\n\n### Phase 1: Discovery\n1. Scan codebase structure - Identify components, modules, layers\n2. Map dependencies - Internal and external relationships\n3. Identify entry points - Public APIs, commands, interfaces\n\n### Phase 2: Functional Analysis\n1. Inventory features - What capabilities exist\n2. Trace behaviors - How features work end-to-end\n3. Identify gaps - Missing or incomplete functionality\n\n### Phase 3: Practical Analysis\n1. Assess performance - Latency, throughput, resource usage\n2. Evaluate usability - Developer experience, API design\n3. Check operations - Logging, monitoring, error handling\n\n### Phase 4: Foundation Analysis\n1. Pattern recognition - What patterns are used\n2. Principle check - SOLID, DRY, KISS adherence\n3. Debt assessment - Technical debt inventory\n\n### Phase 5: Synthesis\n1. Cross-reference findings - Connect issues across perspectives\n2. Prioritize recommendations - Based on impact and effort\n3. Generate report - Structured findings and actions\n\n## FPF Report Template\n\n```markdown\n# FPF Architecture Review: [Project/Component]\n\n**Date:** [DATE]\n**Scope:** [what was reviewed]\n\n## Executive Summary\n[2-3 sentence overview of findings]\n\n## Functional Perspective\n### Features Inventory\n| Feature | Status | Notes |\n|---------|--------|-------|\n| [Feature 1] | Complete | - |\n\n### Capability Gaps\n1. [Gap 1] - [Impact]\n\n## Practical Perspective\n### Performance Assessment\n| Metric | Current | Target | Status |\n|--------|---------|--------|--------|\n| [Metric 1] | [value] | [target] | PASS/FAIL |\n\n## Foundation Perspective\n### Pattern Analysis\n| Pattern | Usage | Assessment |\n|---------|-------|------------|\n| [Pattern 1] | [where used] | Appropriate/Problematic |\n\n### Technical Debt\n| Item | Severity | Effort | Priority |\n|------|----------|--------|----------|\n| [Debt 1] | High | Medium | P1 |\n\n## Recommendations\n### High Priority\n1. **[Recommendation]** - Impact: [what improves] - Effort: [estimate]\n```\n\n## Configuration\n\n```yaml\nperspectives:\n  functional:\n    enabled: true\n    depth: \"full\"  # full, summary\n  practical:\n    enabled: true\n    depth: \"full\"\n  foundation:\n    enabled: true\n    depth: \"full\"\n```\n\n## Guardrails\n\n1. **Scope boundaries** - Stay within configured scope\n2. **Evidence-based** - Every finding needs supporting evidence\n3. **Actionable output** - Recommendations must be actionable\n4. **Balanced perspectives** - Don't over-index on one perspective\n\n## References\n\n- [FPF Framework](https://github.com/ailev/FPF) - Original methodology\n- [quint-code](https://github.com/m0n0x41d/quint-code) - Heavy implementation (this skill is lighter)\n\nFile v1.9.17:modules/principle-checks.md\n\n---\nname: principle-checks\ndescription: Law of Demeter, anti-slop patterns, AI guardrails, and security/performance checks\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [principles, demeter, anti-patterns, security, performance, quality]\ncomplexity: advanced\nestimated_tokens: 500\n---\n\n# Principle Checks Module\n\nSystematic verification of architectural principles, anti-patterns, and quality attributes.\n\n## Law of Demeter (LoD)\n\n### The Principle\n\n\"Talk to friends, not to strangers.\"\n\nAn object should only call methods on:\n1. Itself\n2. Its parameters\n3. Objects it creates\n4. Its direct components\n\n### Train Wreck Detection\n\n**Anti-pattern:**\n```python\n# Bad: Chain of calls\ncustomer.get_address().get_city().get_postal_code()\n\n# Bad: Multiple dereferences\norder.customer.billing_address.street\n\n# Bad: Deep navigation\ncontext.request.session.user.preferences.theme\n```\n\n**Search patterns:**\n```bash\n# Python\ngrep -rn '\\.\\w\\+(\\)\\.\\w\\+(\\)\\.\\w\\+(' src/\n\n# JavaScript/TypeScript\ngrep -rn '\\.\\w\\+\\.\\w\\+\\.\\w\\+' src/ --include=\"*.js\" --include=\"*.ts\"\n\n# Count violations\ngrep -r '\\.\\w\\+\\.\\w\\+\\.\\w\\+' src/ | wc -l\n```\n\n### Refactoring Strategies\n\n**Strategy 1: Tell, Don't Ask**\n```python\n# Before\nif customer.get_address().get_country() == \"US\":\n    apply_us_tax()\n\n# After\nif customer.is_in_country(\"US\"):\n    apply_us_tax()\n```\n\n**Strategy 2: Move Logic to Owner**\n```python\n# Before\npostal_code = customer.get_address().get_postal_code()\nregion = lookup_region(postal_code)\n\n# After\nregion = customer.get_region()  # Address logic inside Customer\n```\n\n**Strategy 3: Introduce Facade**\n```python\n# Before\nconfig.get_database().get_connection_pool().get_connection()\n\n# After\nconfig.get_database_connection()  # Facade hides complexity\n```\n\n## Anti-Slop Checks\n\n### What is \"Slop\"?\n\nCode that appears professional but lacks substance:\n- Generic naming\n- Overengineering\n- Cargo cult patterns\n- Hallucinated dependencies\n- Hollow abstractions\n\n### Detection Patterns\n\n**1. Overengineering Red Flags:**\n```python\n# Bad: Unnecessary abstraction layers\nclass UserFactoryFactory:\n    def create_user_factory(self):\n        return UserFactory()\n\n# Bad: Premature generalization\nclass AbstractBaseEntityManagerInterface:\n    pass\n```\n\n**Search:**\n```bash\n# Find \"Abstract\" overuse\ngrep -r \"class Abstract\" src/ | wc -l\n\n# Find \"Manager\" bloat\ngrep -r \"Manager\\|Handler\\|Processor\" src/ --include=\"*.py\"\n\n# Find deep inheritance\ngrep -A 5 \"class.*:\" src/**/*.py | grep \"    class\"\n```\n\n**2. Generic Naming:**\n```python\n# Bad: Non-descriptive names\ndef process_data(data):\n    result = handle_item(data)\n    return do_thing(result)\n\n# Good: Specific names\ndef calculate_tax(order):\n    taxable_amount = extract_taxable_items(order)\n    return apply_tax_rate(taxable_amount)\n```\n\n**Search:**\n```bash\n# Find generic names\ngrep -rn \"process\\|handle\\|manage\\|do_\\|data\\|item\\|thing\" src/\n```\n\n**3. Hidden Fragility:**\n```python\n# Bad: Silent failure\ntry:\n    critical_operation()\nexcept Exception:\n    pass  # Swallowed error\n\n# Bad: Implicit coupling\nglobal_state = {}  # Hidden dependency\n\n# Bad: Magic values\nif status == 42:  # What does 42 mean?\n```\n\n**Search:**\n```bash\n# Find bare except\ngrep -rn \"except:\" src/\n\n# Find global state\ngrep -rn \"^[A-Z_]\\+ = \" src/\n\n# Find magic numbers\ngrep -rn \"if.*== [0-9]\\+\" src/\n```\n\n**4. Hallucinated Dependencies:**\n```python\n# Bad: Assuming non-existent methods\nuser.auto_validate()  # Does this exist?\ncache.smart_invalidate()  # What does \"smart\" mean?\n\n# Bad: Imaginary patterns\n@auto_retry  # Not in codebase\n@cache_result  # Decorator doesn't exist\n```\n\n**Verification:**\n```bash\n# Check decorator existence\ngrep -r \"^def auto_retry\\|^class auto_retry\" src/\n\n# Verify method definitions\ngrep -r \"def auto_validate\" src/\n```\n\n## Guardrails for AI Assistance\n\n### Evidence-Based Critiques\n\n**Required:**\n- File paths\n- Line numbers\n- Actual code snippets\n- Measured metrics\n\n**Forbidden:**\n- \"Looks like...\"\n- \"Probably should...\"\n- \"Best practice is...\"\n- \"Generally we...\"\n\n### Trade-Off Statements\n\n**Good:**\n```\nOption A: PostgreSQL\n+ Proven reliability, ACID compliance\n+ Team expertise\n- Higher hosting cost\n- Vertical scaling limits\n\nOption B: DynamoDB\n+ Horizontal scalability\n+ Lower latency\n- Team learning curve\n- Complex query limitations\n```\n\n**Bad:**\n```\n\"PostgreSQL is better for this use case.\"\n\"DynamoDB would be more scalable.\"\n```\n\n### Replace Hollow Phrases\n\n| Hollow Phrase | Replace With |\n|--------------|--------------|\n| \"Clean code\" | Specific principle (SRP, LoD) |\n| \"Best practice\" | Cited guideline or measured benefit |\n| \"Should be\" | Evidence-based observation |\n| \"More maintainable\" | Specific metric (coupling, complexity) |\n| \"Industry standard\" | Named standard (RESTful, OAuth 2.0) |\n\n## Security Checks\n\n### Input Validation\n\n**1. Boundary Validation:**\n```python\n# Check: All external inputs validated\n@validate_input\ndef create_user(email: str, age: int):\n    if not is_valid_email(email):\n        raise ValidationError(\"Invalid email\")\n    if not (0 < age < 150):\n        raise ValidationError(\"Invalid age\")\n```\n\n**Search:**\n```bash\n# Find unvalidated endpoints\ngrep -rn \"@app.route\\|@api\" src/ -A 10 | grep -v \"validate\\|check\\|verify\"\n```\n\n**2. SQL Injection Prevention:**\n```python\n# Bad\nquery = f\"SELECT * FROM users WHERE id = {user_id}\"\n\n# Good\nquery = \"SELECT * FROM users WHERE id = ?\"\ncursor.execute(query, (user_id,))\n```\n\n**Search:**\n```bash\n# Find string interpolation in SQL\ngrep -rn \"f\\\".*SELECT\\|\\\".*SELECT.*{\" src/\n```\n\n**3. XSS Prevention:**\n```python\n# Check for auto-escaping\n# Framework default: Flask (manual), Django (auto)\n```\n\n### Least Privilege\n\n**1. Minimum Permissions:**\n```python\n# Bad: Admin for everything\ndb_user = \"admin\"\n\n# Good: Specific roles\ndb_user = \"app_readonly\"  # For queries\ndb_user = \"app_writer\"    # For mutations\n```\n\n**2. Capability Checks:**\n```bash\n# Find permission checks\ngrep -rn \"check_permission\\|require_role\\|authorize\" src/\n```\n\n### Error Handling\n\n**1. No Sensitive Leaks:**\n```python\n# Bad\nexcept Exception as e:\n    return {\"error\": str(e)}  # May expose internals\n\n# Good\nexcept Exception as e:\n    logger.error(f\"Operation failed: {e}\")\n    return {\"error\": \"Operation failed\"}\n```\n\n**2. Proper Logging:**\n```bash\n# Check logging coverage\ngrep -rn \"logger\\.\\(error\\|warning\\)\" src/ | wc -l\n```\n\n## Performance Checks\n\n### Performance Budgets\n\nDefine limits:\n```yaml\nresponse_time:\n  p50: 100ms\n  p95: 500ms\n  p99: 1000ms\n\ndatabase_queries:\n  max_per_request: 10\n\nmemory:\n  max_heap: 512MB\n```\n\n### N+1 Query Detection\n\n```python\n# Bad: N+1 queries\nfor user in users:\n    user.get_orders()  # Query per user\n\n# Good: Eager loading\nusers = User.query.options(joinedload('orders')).all()\n```\n\n**Search:**\n```bash\n# Find potential N+1\ngrep -rn \"for.*in.*:\" src/ -A 3 | grep \"get_\\|fetch_\\|find_\"\n```\n\n### Caching Strategy\n\n**Check for:**\n- Cache key design\n- TTL configuration\n- Invalidation strategy\n- Cache stampede prevention\n\n```bash\n# Find caching usage\ngrep -rn \"@cache\\|cache.get\\|cache.set\" src/\n```\n\n### Index Coverage\n\n```bash\n# Check migrations for indexes\ngrep -r \"CREATE INDEX\\|add_index\" migrations/\n\n# Find missing indexes (slow queries)\n# Review query logs, not static analysis\n```\n\n## Integration with Architecture Review\n\nUse this module during Step 4 (Principle Checks):\n1. Run LoD detection searches\n2. Check for anti-slop patterns\n3. Verify AI assistance guardrails\n4. Execute security checks\n5. Validate performance budgets\n6. Document violations with evidence\n7. Recommend specific fixes with file/line references\n\nFile v1.9.17:skill-card.md\n\n## Description: <br>\nAssesses architecture decisions, ADR compliance, and coupling. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[athola](https://clawhub.ai/user/athola) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and engineers use this skill to review architecture changes, ADR compliance, module coupling, design invariants, and architecture risks before merging significant system changes. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill may activate on broad architecture or design wording. <br>\nMitigation: Invoke it intentionally for architecture review rather than general design discussion. <br>\nRisk: Architecture recommendations can be incorrect or misleading if repository context is incomplete. <br>\nMitigation: Require evidence-backed findings with file paths, line references, and human review before acting on recommendations. <br>\nRisk: The skill includes repository-inspection shell commands. <br>\nMitigation: Review commands before execution and keep them scoped to the target repository. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/athola/skills/nm-pensive-architecture-review) <br>\n- [Declared homepage](https://github.com/athola/claude-night-market/tree/master/plugins/pensive) <br>\n- [FPF Framework](https://github.com/ailev/FPF) <br>\n- [quint-code](https://github.com/m0n0x41d/quint-code) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, guidance] <br>\n**Output Format:** [Markdown guidance with checklists, review sections, command snippets, findings, and recommendations] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Outputs are intended for human review and may include approve, approve-with-actions, or block recommendations.] <br>\n\n## Skill Version(s): <br>\n1.9.17 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.9.16: 7 files, 15277 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), skill-card.md (2202b), SKILL.md (7846b), _meta.json (150b)\n\nFile v1.9.16:SKILL.md\n\n---\nname: architecture-review\ndescription: Assesses architecture decisions, ADR compliance, and coupling\nversion: 1.9.8\ntriggers:\n  - architecture\n  - design\n  - adr\n  - coupling\n  - patterns\n  - principles\n  - evaluating design changes or validating structural decisions before merging\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/athola/claude-night-market/tree/master/plugins/pensive\", \"emoji\": \"\\ud83c\\udfd7\\ufe0f\", \"requires\": {\"config\": [\"night-market.pensive:shared\", \"night-market.imbue:proof-of-work\", \"night-market.imbue:diff-analysis/modules/risk-assessment-framework\"]}}}\nsource: claude-night-market\nsource_plugin: pensive\n---\n\n> **Night Market Skill** — ported from [claude-night-market/pensive](https://github.com/athola/claude-night-market/tree/master/plugins/pensive). For the full experience with agents, hooks, and commands, install the Claude Code plugin.\n\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [When to Use](#when-to-use)\n- [Progressive Loading](#progressive-loading)\n- [Required TodoWrite Items](#required-todowrite-items)\n- [Workflow](#workflow)\n- [Step 1: Establish Context (`arch-review:context-established`)](#step-1:-establish-context-(arch-review:context-established))\n- [Step 2: ADR Audit (`arch-review:adr-audit`)](#step-2:-adr-audit-(arch-review:adr-audit))\n- [Step 3: Interaction Mapping (`arch-review:interaction-mapping`)](#step-3:-interaction-mapping-(arch-review:interaction-mapping))\n- [Step 4: Principle Checks (`arch-review:principle-checks`)](#step-4:-principle-checks-(arch-review:principle-checks))\n- [Step 5: Risks and Actions (`arch-review:risks-actions`)](#step-5:-risks-and-actions-(arch-review:risks-actions))\n- [Testing](#testing)\n\n## Testing\n\nRun `pytest plugins/pensive/tests/skills/test_architecture_review.py` to verify review logic.\n- [Architecture Principles Checklist](#architecture-principles-checklist)\n- [Coupling](#coupling)\n- [Cohesion](#cohesion)\n- [Layering](#layering)\n- [Evolution](#evolution)\n\n\n# Architecture Review Workflow\n\nArchitecture assessment against ADRs and design principles.\n\n## Quick Start\n\n```bash\n/architecture-review\n```\n\n## When To Use\n\n- Approving reimplementations.\n- Large-scale refactoring reviews.\n- System design changes.\n- New module/service introduction.\n- Dependency restructuring.\n\n## When NOT To Use\n\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n\n## Progressive Loading\n\nLoad modules based on review scope:\n\n- **`modules/adr-audit.md`** (~400 tokens): ADR verification and documentation.\n- **`modules/coupling-analysis.md`** (~450 tokens): Dependency analysis and boundary violations.\n- **`modules/principle-checks.md`** (~500 tokens): Code quality, security, and performance.\n- **`modules/fpf-methodology.md`** (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.\n\nLoad all modules for full reviews. For focused reviews, load only relevant modules.\n\n## Required TodoWrite Items\n\n1. `arch-review:context-established`: Repository, branch, motivation.\n2. `arch-review:adr-audit`: ADR verification and new ADR needs.\n3. `arch-review:interaction-mapping`: Module coupling analysis.\n4. `arch-review:invariant-check`: Invariant conflict detection and 3-option analysis.\n5. `arch-review:principle-checks`: LoD, security, performance.\n6. `arch-review:risks-actions`: Recommendation and follow-ups.\n\n## Workflow\n\n### Step 1: Establish Context (`arch-review:context-established`)\n\nConfirm repository and branch:\n```bash\npwd\ngit status -sb\n```\n\nDocument:\n- Feature/bug/epic motivating review.\n- Affected subsystems.\n- Architectural intent from README/docs.\n- Design trade-off assumptions.\n\n### Step 2: ADR Audit (`arch-review:adr-audit`)\n\n**Load: `modules/adr-audit.md`**\n\n- Locate ADRs in project.\n- Verify required sections.\n- Check status flow.\n- Confirm immutability compliance.\n- Flag need for new ADRs.\n\n### Step 3: Interaction Mapping (`arch-review:interaction-mapping`)\n\n**Load: `modules/coupling-analysis.md`**\n\n- Diagram before/after module interactions.\n- Verify composition boundaries.\n- Check data ownership clarity.\n- Validate dependency flow direction.\n- Identify coupling violations.\n\n### Step 3.5: Invariant Conflict Detection (`arch-review:invariant-check`)\n\nBefore checking principles, identify whether the changes\nconflict with existing design invariants. This is the\nhighest-judgment step in architecture review — models\nget this wrong more often than any other call.\n\n**Identify existing invariants:**\n\n1. Scan ADRs for recorded decisions still in \"accepted\"\n   status\n2. Check module boundaries (are imports crossing layers\n   that previously didn't?)\n3. Check data flow direction (does data now flow in a\n   new direction?)\n4. Check API contracts (are public interfaces changing\n   shape?)\n5. Check structural patterns (is a new pattern being\n   introduced alongside an existing one?)\n\n```bash\n# Detect boundary crossings in changed files\ngit diff --name-only | while read f; do\n  head -20 \"$f\" 2>/dev/null | rg \"^(import|from|use |require)\" || true\ndone\n```\n\n**When a conflict is detected:**\n\nDo NOT recommend a resolution. Present the three options\nand escalate to human judgment:\n\n| Option | When Right | When Wrong |\n|--------|------------|------------|\n| **Preserve invariant** (reject feature) | Invariant simplifies many things; feature is marginal | Feature is genuinely needed and invariant is stale |\n| **Layer on top** (add inelegantly) | Feature is needed; invariant still valuable; imperfection is OK | Layering creates a maintenance trap that will compound |\n| **Revise invariant** (change the design) | Genuine new learning invalidates the original reasoning | You're \"cleaning up\" a decision you don't fully understand |\n\n**Output format:**\n\n```markdown\n### Invariant Conflicts\n\n[I1] **[Invariant name]** — [what decision it represents]\n- **Conflict**: [what change clashes]\n- **Options**: Preserve / Layer / Revise\n- **Recommendation**: ESCALATE TO HUMAN\n- **Risk if wrong**: [what compounds]\n```\n\n**Why this matters:** Bad invariant decisions compound.\nAfter a few wrong calls the codebase becomes\nunsalvageable. This is a judgment problem, not a context\nproblem — the agent should surface it, not solve it.\n\n### Step 4: Principle Checks (`arch-review:principle-checks`)\n\n**Load: `modules/principle-checks.md`**\n\n- Law of Demeter.\n- Anti-slop patterns.\n- Security (input validation, least privilege).\n- Performance (N+1 queries, caching).\n\n### Step 5: Risks and Actions (`arch-review:risks-actions`)\n\nSummarize using `imbue:diff-analysis/modules/risk-assessment-framework`:\n- Current vs proposed architecture.\n- Business impact.\n- Technical debt implications.\n\nList follow-ups with owners and dates.\n\nProvide recommendation:\n- **Approve**: Architecture sound.\n- **Approve with actions**: Minor issues to address.\n- **Block**: Fundamental problems requiring redesign.\n\n## Architecture Principles Checklist\n\n### Coupling\n- [ ] Dependencies follow defined boundaries.\n- [ ] No circular dependencies.\n- [ ] Extension points used properly.\n- [ ] Abstractions don't leak.\n\n### Cohesion\n- [ ] Related functionality grouped.\n- [ ] Single responsibility per module.\n- [ ] Clear module purposes.\n\n### Layering\n- [ ] Layers have clear responsibilities.\n- [ ] Dependencies flow downward.\n- [ ] No layer bypassing.\n\n### Invariants\n- [ ] Existing design invariants identified.\n- [ ] Conflicts between changes and invariants surfaced.\n- [ ] Three-option analysis (preserve/layer/revise) presented.\n- [ ] Invariant changes escalated to human judgment.\n- [ ] No silent invariant revisions in the diff.\n\n### Evolution\n- [ ] Changes are reversible.\n- [ ] Migration paths are clear.\n- [ ] ADRs document decisions.\n\nFile v1.9.16:_meta.json\n\n{\n  \"ownerId\": \"kn7d107jg9jv602h9ytsegydq184a42s\",\n  \"slug\": \"nm-pensive-architecture-review\",\n  \"version\": \"1.9.16\",\n  \"publishedAt\": 1784058919195\n}\n\nFile v1.9.16:modules/adr-audit.md\n\n---\nname: adr-audit\ndescription: Architecture Decision Record audit patterns and verification workflows\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [adr, documentation, governance, decisions]\ncomplexity: intermediate\nestimated_tokens: 400\n---\n\n# ADR Audit Module\n\ndetailed ADR discovery, validation, and governance patterns.\n\n## ADR Location Patterns\n\nCommon ADR locations by project type:\n\n```bash\n# Standard locations\nwiki/architecture/\ndocs/adr/\ndocs/decisions/\narchitecture/decisions/\n.adr/\n\n# Search pattern\nfind . -type f -name \"*ADR*\" -o -name \"*decision*\" | grep -E \"\\.(md|txt)$\"\n```\n\n## Required ADR Sections\n\nEvery ADR must include:\n\n### 1. Title\nClear, specific decision statement:\n- \"Use PostgreSQL for primary datastore\"\n- \"Adopt hexagonal architecture pattern\"\n- \"Implement JWT-based authentication\"\n\n### 2. Status\nMust follow strict progression:\n```\nProposed → Reviewed → Accepted\n                    ↓\n              Superseded (when invalidated)\n```\n\n**Rules:**\n- Status changes are append-only\n- Date each status transition\n- Never delete/modify accepted ADRs\n- Use \"Superseded by ADR-XXX\" to replace\n\n### 3. Context\nDocument the forces at play:\n- Business requirements\n- Technical constraints\n- Team capabilities\n- Timeline pressures\n- Existing architecture\n\n### 4. Decision\nThe \"we will...\" statement:\n- Clear action chosen\n- Implementation approach\n- Key design choices\n\n### 5. Alternatives Considered\nFor each alternative:\n- Description\n- Pros/cons\n- Why rejected\n\nMinimum 2 alternatives required.\n\n### 6. Consequences\n\n**Positive:**\n- Benefits gained\n- Problems solved\n- Capabilities enabled\n\n**Negative:**\n- Trade-offs accepted\n- Technical debt incurred\n- Complexity added\n\n**Neutral:**\n- Changes required\n- Migration steps\n- Training needs\n\n### 7. Metadata\n```yaml\nDate: YYYY-MM-DD\nAuthor: [name]\nStatus: [status]\nSupersedes: [ADR-XXX] (if applicable)\nSuperseded-by: [ADR-XXX] (if applicable)\n```\n\n## Status Flow Verification\n\n### Valid Transitions\n- Proposed → Reviewed\n- Reviewed → Accepted\n- Reviewed → Rejected\n- Accepted → Superseded (via new ADR only)\n\n### Invalid Transitions\n- Proposed -> Accepted (skip review)\n- Accepted -> Rejected (use Superseded)\n- Superseded -> Accepted (immutable)\n\n## Immutability Rules\n\n**Once Accepted:**\n1. **Never modify** decision content\n2. **Never change** consequences\n3. **Never delete** the ADR\n4. **Only append** status changes\n\n**To Replace:**\n1. Create new ADR with superseding decision\n2. Add \"Supersedes: ADR-XXX\" to new ADR\n3. Add \"Superseded-by: ADR-YYY\" to old ADR\n4. Update old ADR status to \"Superseded\"\n\n## Audit Workflow\n\n### 1. Locate All ADRs\n```bash\n# Find ADR directory\nls -la docs/adr/ wiki/architecture/ 2>/dev/null\n\n# Count ADRs\nfind . -path \"*/adr/*.md\" -o -path \"*/decisions/*.md\" | wc -l\n```\n\n### 2. Verify Structure\nFor each ADR:\n- [ ] Has all required sections\n- [ ] Status follows valid flow\n- [ ] Dates are present\n- [ ] Alternatives documented (≥2)\n- [ ] Consequences specified\n\n### 3. Check References\n```bash\n# Find ADR references in code\ngrep -r \"ADR-[0-9]\" --include=\"*.md\" --include=\"*.py\" --include=\"*.js\"\n\n# Verify backlinks\ngrep \"Superseded-by\" docs/adr/*.md\n```\n\n### 4. Flag Issues\nCommon problems:\n- Missing sections\n- Invalid status transitions\n- Modified accepted ADRs\n- Missing supersession links\n- Insufficient alternatives\n\n## New ADR Requirements\n\nFlag need for new ADR when:\n- Introducing new architectural pattern\n- Changing core technology\n- Modifying system boundaries\n- Adding external dependencies\n- Changing security model\n\n**Before implementation:**\n1. Draft ADR with all sections\n2. Set status: Proposed\n3. Request review\n4. Update to Reviewed\n5. Gain approval → Accepted\n6. Then proceed with implementation\n\n## Integration with Architecture Review\n\nUse this module during Step 2 (ADR Audit):\n1. Locate ADRs using patterns\n2. Verify structure completeness\n3. Check status flow validity\n4. Confirm immutability compliance\n5. Identify missing ADRs for current work\n6. Draft new ADRs if needed\n\nFile v1.9.16:modules/coupling-analysis.md\n\n---\nname: coupling-analysis\ndescription: Interaction mapping, composition boundaries, and dependency flow analysis\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [coupling, dependencies, composition, boundaries, modularity]\ncomplexity: advanced\nestimated_tokens: 450\n---\n\n# Coupling Analysis Module\n\nSystematic analysis of module interactions, boundaries, and dependency flows.\n\n## Interaction Mapping Patterns\n\n### Visual Representation\n\nCreate before/after diagrams:\n\n```\nBefore:\n┌─────────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│Module B │────▶│ Database │\n└─────────┘     └─────────┘     └──────────┘\n\nAfter:\n┌─────────┐     ┌───────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│ Cache │────▶│Module B │────▶│ Database │\n└─────────┘     └───────┘     └─────────┘     └──────────┘\n```\n\n### Dependency Graph Tools\n\n```bash\n# Python: Generate import graph\npydeps --max-bacon=2 --cluster src/\n\n# TypeScript: Analyze module dependencies\nmadge --circular --extensions ts src/\n\n# Generic: Find direct dependencies\ngrep -r \"import\\|require\\|from\" src/ | cut -d: -f1 | sort | uniq -c\n```\n\n## Composition Boundaries\n\n### Boundary Definition\n\nClear boundaries have:\n1. **Explicit interfaces** - Published contracts\n2. **Data ownership** - Single source of truth\n3. **Encapsulation** - Hidden implementation\n4. **Stability** - Minimal breaking changes\n\n### Boundary Types\n\n**Module Boundaries:**\n```\n┌──────────────────────────┐\n│   Public API             │\n├──────────────────────────┤\n│   Internal Logic         │\n│   (implementation)       │\n└──────────────────────────┘\n```\n\n**Layer Boundaries:**\n```\n┌──────────────────────────┐\n│   Presentation Layer     │ ← HTTP/UI\n├──────────────────────────┤\n│   Application Layer      │ ← Business Logic\n├──────────────────────────┤\n│   Domain Layer           │ ← Core Models\n├──────────────────────────┤\n│   Infrastructure Layer   │ ← Database/External\n└──────────────────────────┘\n```\n\n**Service Boundaries:**\n```\nService A          Service B\n┌────────┐        ┌────────┐\n│  API   │◀──────▶│  API   │\n├────────┤        ├────────┤\n│  DB A  │        │  DB B  │\n└────────┘        └────────┘\n```\n\n### Boundary Violations\n\n**Ad-hoc Reach-ins:**\n```python\n# Bad: Reaching through module boundary\nuser.profile.settings.theme.get_color()\n\n# Good: Ask for what you need\nuser.get_theme_color()\n```\n\n**Layering Violations:**\n```python\n# Bad: Domain layer accessing infrastructure\nclass Order:\n    def save(self):\n        db.execute(\"INSERT INTO orders...\")\n\n# Good: Infrastructure handles persistence\nclass OrderRepository:\n    def save(self, order: Order):\n        db.execute(\"INSERT INTO orders...\")\n```\n\n## Data Ownership Analysis\n\n### Single Owner Principle\n\nEach data entity has exactly one authoritative owner:\n\n```\nUser Data:\n├── Auth Service (owner: credentials)\n├── Profile Service (owner: profile data)\n└── Analytics Service (consumer: read-only)\n```\n\n### Ownership Violations\n\n**Multiple Writers:**\n```python\n# Bad: Two services modify same data\nauth_service.update_user_email()\nprofile_service.update_user_email()\n\n# Good: Single owner\nprofile_service.update_email()  # Publishes event\nauth_service.handle_email_changed()  # Subscribes to event\n```\n\n**Ownership Leaks:**\n```python\n# Bad: Exposing internal structure\ndef get_user():\n    return user_database_model\n\n# Good: Return boundary type\ndef get_user():\n    return UserDTO(id=..., name=...)\n```\n\n## Dependency Flow Checking\n\n### Expected Flow Patterns\n\n**Layered Architecture:**\n```\nPresentation → Application → Domain → Infrastructure\n     ↓              ↓           ↓            ↓\n  (no reverse dependencies allowed)\n```\n\n**Hexagonal Architecture:**\n```\n     ┌─────────────┐\n     │   Domain    │ ← Core (no dependencies)\n     └──────┬──────┘\n            │\n  ┌─────────┴─────────┐\n  │   Application     │ ← Orchestration\n  └────────┬──────────┘\n           │\n  ┌────────┴─────────┐\n  │   Adapters       │ ← External interfaces\n  └──────────────────┘\n```\n\n### Circular Dependency Detection\n\n```bash\n# Python\npydeps --show-cycles src/\n\n# JavaScript/TypeScript\nmadge --circular src/\n\n# Manual check\ngrep -r \"from.*import\" src/ | # Extract all imports\n  python -c \"\nimport sys\nfrom collections import defaultdict\n\ngraph = defaultdict(set)\nfor line in sys.stdin:\n    # Parse: file imports module\n    # Build graph, detect cycles\n\"\n```\n\n### Dependency Metrics\n\n**Afferent Coupling (Ca):**\nNumber of modules that depend on this module.\n- High Ca = Stable (many dependents)\n\n**Efferent Coupling (Ce):**\nNumber of modules this module depends on.\n- High Ce = Unstable (many dependencies)\n\n**Instability (I):**\n```\nI = Ce / (Ca + Ce)\n```\n- I = 0: Maximally stable\n- I = 1: Maximally unstable\n\n### Ideal Patterns\n\n**Stable Abstractions:**\n- Core domain: Low I (stable)\n- Infrastructure: High I (unstable, replaceable)\n\n**Dependency Direction:**\n```\nUnstable → Stable\n(changing) depends on (stable)\n```\n\n## Side Effects Analysis\n\n### Side Effect Categories\n\n**1. State Mutations:**\n```python\n# Track mutations\ndef process_order(order):\n    order.status = \"PROCESSED\"  # Mutation\n    notify_customer(order)       # Side effect\n    log_event(order)            # Side effect\n```\n\n**2. External I/O:**\n- Database writes\n- API calls\n- File operations\n- Message queue publishing\n\n**3. Timing Dependencies:**\n- Caching\n- Rate limiting\n- Session management\n\n### Containment Strategies\n\n**Command-Query Separation:**\n```python\n# Query: No side effects\ndef get_order_total(order): -> Decimal\n\n# Command: Mutations allowed\ndef place_order(order) -> None\n```\n\n**Effect Tracking:**\n```python\n# Explicit effect types\nEffect = Database | API | Cache | Event\n\ndef process_payment(order) -> tuple[Result, list[Effect]]:\n    effects = []\n    # Track all effects\n    return result, effects\n```\n\n## Cross-Boundary Dependencies\n\n### Allowed Patterns\n\n**1. Events:**\n```python\n# Service A publishes\nevent_bus.publish(UserCreated(user_id))\n\n# Service B subscribes\n@subscribe(UserCreated)\ndef handle_user_created(event):\n    # React independently\n```\n\n**2. Shared Kernel:**\n```python\n# Common domain types\nfrom shared.types import Money, UserId, Email\n```\n\n**3. Published APIs:**\n```python\n# Service B calls Service A's API\nresponse = service_a_client.get_user(user_id)\n```\n\n### Forbidden Patterns\n\n**1. Shared Database:**\n```python\n# Bad: Direct database access across services\nuser_db.query(\"SELECT * FROM users\")  # From order service\n```\n\n**2. Implementation Sharing:**\n```python\n# Bad: Importing internal modules\nfrom service_a.internal.helpers import format_date\n```\n\n## Integration with Architecture Review\n\nUse this module during Step 3 (Interaction Mapping):\n1. Map all module interactions (before/after)\n2. Verify composition boundaries\n3. Check data ownership clarity\n4. Validate dependency flow direction\n5. Detect circular dependencies\n6. Identify coupling violations\n7. Analyze side effect containment\n\nFile v1.9.16:modules/fpf-methodology.md\n\n# FPF Architecture Review Methodology\n\nConduct architecture reviews using the FPF (Functional, Practical, Foundation) methodology, evaluating codebases through three complementary perspectives.\n\n## Philosophy\n\nArchitecture reviews should be systematic and multi-dimensional. FPF provides three lenses:\n- **Functional**: What the system does (capabilities, behaviors)\n- **Practical**: How well it works (performance, usability)\n- **Foundation**: What it's built on (principles, patterns)\n\n## Quick Start\n\n```bash\n# Full FPF review\n/architecture-review --methodology fpf\n\n# Specific perspective\n/architecture-review --perspective functional\n/architecture-review --perspective practical\n/architecture-review --perspective foundation\n```\n\n## The Three Perspectives\n\n### 1. Functional Perspective\n\n**Question:** What does this system do?\n\n**Evaluates:**\n- Feature completeness\n- Capability coverage\n- Behavior correctness\n- Integration points\n\n**Outputs:**\n- Feature inventory\n- Capability gaps\n- Behavior anomalies\n\n### 2. Practical Perspective\n\n**Question:** How well does this system work?\n\n**Evaluates:**\n- Performance characteristics\n- Usability patterns\n- Operational concerns\n- Scalability considerations\n\n**Outputs:**\n- Performance assessment\n- Usability issues\n- Operational recommendations\n\n### 3. Foundation Perspective\n\n**Question:** What is this system built on?\n\n**Evaluates:**\n- Architectural patterns\n- Design principles\n- Code quality\n- Technical debt\n\n**Outputs:**\n- Pattern analysis\n- Principle adherence\n- Debt inventory\n\n## FPF Workflow\n\n### Phase 1: Discovery\n1. Scan codebase structure - Identify components, modules, layers\n2. Map dependencies - Internal and external relationships\n3. Identify entry points - Public APIs, commands, interfaces\n\n### Phase 2: Functional Analysis\n1. Inventory features - What capabilities exist\n2. Trace behaviors - How features work end-to-end\n3. Identify gaps - Missing or incomplete functionality\n\n### Phase 3: Practical Analysis\n1. Assess performance - Latency, throughput, resource usage\n2. Evaluate usability - Developer experience, API design\n3. Check operations - Logging, monitoring, error handling\n\n### Phase 4: Foundation Analysis\n1. Pattern recognition - What patterns are used\n2. Principle check - SOLID, DRY, KISS adherence\n3. Debt assessment - Technical debt inventory\n\n### Phase 5: Synthesis\n1. Cross-reference findings - Connect issues across perspectives\n2. Prioritize recommendations - Based on impact and effort\n3. Generate report - Structured findings and actions\n\n## FPF Report Template\n\n```markdown\n# FPF Architecture Review: [Project/Component]\n\n**Date:** [DATE]\n**Scope:** [what was reviewed]\n\n## Executive Summary\n[2-3 sentence overview of findings]\n\n## Functional Perspective\n### Features Inventory\n| Feature | Status | Notes |\n|---------|--------|-------|\n| [Feature 1] | Complete | - |\n\n### Capability Gaps\n1. [Gap 1] - [Impact]\n\n## Practical Perspective\n### Performance Assessment\n| Metric | Current | Target | Status |\n|--------|---------|--------|--------|\n| [Metric 1] | [value] | [target] | PASS/FAIL |\n\n## Foundation Perspective\n### Pattern Analysis\n| Pattern | Usage | Assessment |\n|---------|-------|------------|\n| [Pattern 1] | [where used] | Appropriate/Problematic |\n\n### Technical Debt\n| Item | Severity | Effort | Priority |\n|------|----------|--------|----------|\n| [Debt 1] | High | Medium | P1 |\n\n## Recommendations\n### High Priority\n1. **[Recommendation]** - Impact: [what improves] - Effort: [estimate]\n```\n\n## Configuration\n\n```yaml\nperspectives:\n  functional:\n    enabled: true\n    depth: \"full\"  # full, summary\n  practical:\n    enabled: true\n    depth: \"full\"\n  foundation:\n    enabled: true\n    depth: \"full\"\n```\n\n## Guardrails\n\n1. **Scope boundaries** - Stay within configured scope\n2. **Evidence-based** - Every finding needs supporting evidence\n3. **Actionable output** - Recommendations must be actionable\n4. **Balanced perspectives** - Don't over-index on one perspective\n\n## References\n\n- [FPF Framework](https://github.com/ailev/FPF) - Original methodology\n- [quint-code](https://github.com/m0n0x41d/quint-code) - Heavy implementation (this skill is lighter)\n\nFile v1.9.16:modules/principle-checks.md\n\n---\nname: principle-checks\ndescription: Law of Demeter, anti-slop patterns, AI guardrails, and security/performance checks\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [principles, demeter, anti-patterns, security, performance, quality]\ncomplexity: advanced\nestimated_tokens: 500\n---\n\n# Principle Checks Module\n\nSystematic verification of architectural principles, anti-patterns, and quality attributes.\n\n## Law of Demeter (LoD)\n\n### The Principle\n\n\"Talk to friends, not to strangers.\"\n\nAn object should only call methods on:\n1. Itself\n2. Its parameters\n3. Objects it creates\n4. Its direct components\n\n### Train Wreck Detection\n\n**Anti-pattern:**\n```python\n# Bad: Chain of calls\ncustomer.get_address().get_city().get_postal_code()\n\n# Bad: Multiple dereferences\norder.customer.billing_address.street\n\n# Bad: Deep navigation\ncontext.request.session.user.preferences.theme\n```\n\n**Search patterns:**\n```bash\n# Python\ngrep -rn '\\.\\w\\+(\\)\\.\\w\\+(\\)\\.\\w\\+(' src/\n\n# JavaScript/TypeScript\ngrep -rn '\\.\\w\\+\\.\\w\\+\\.\\w\\+' src/ --include=\"*.js\" --include=\"*.ts\"\n\n# Count violations\ngrep -r '\\.\\w\\+\\.\\w\\+\\.\\w\\+' src/ | wc -l\n```\n\n### Refactoring Strategies\n\n**Strategy 1: Tell, Don't Ask**\n```python\n# Before\nif customer.get_address().get_country() == \"US\":\n    apply_us_tax()\n\n# After\nif customer.is_in_country(\"US\"):\n    apply_us_tax()\n```\n\n**Strategy 2: Move Logic to Owner**\n```python\n# Before\npostal_code = customer.get_address().get_postal_code()\nregion = lookup_region(postal_code)\n\n# After\nregion = customer.get_region()  # Address logic inside Customer\n```\n\n**Strategy 3: Introduce Facade**\n```python\n# Before\nconfig.get_database().get_connection_pool().get_connection()\n\n# After\nconfig.get_database_connection()  # Facade hides complexity\n```\n\n## Anti-Slop Checks\n\n### What is \"Slop\"?\n\nCode that appears professional but lacks substance:\n- Generic naming\n- Overengineering\n- Cargo cult patterns\n- Hallucinated dependencies\n- Hollow abstractions\n\n### Detection Patterns\n\n**1. Overengineering Red Flags:**\n```python\n# Bad: Unnecessary abstraction layers\nclass UserFactoryFactory:\n    def create_user_factory(self):\n        return UserFactory()\n\n# Bad: Premature generalization\nclass AbstractBaseEntityManagerInterface:\n    pass\n```\n\n**Search:**\n```bash\n# Find \"Abstract\" overuse\ngrep -r \"class Abstract\" src/ | wc -l\n\n# Find \"Manager\" bloat\ngrep -r \"Manager\\|Handler\\|Processor\" src/ --include=\"*.py\"\n\n# Find deep inheritance\ngrep -A 5 \"class.*:\" src/**/*.py | grep \"    class\"\n```\n\n**2. Generic Naming:**\n```python\n# Bad: Non-descriptive names\ndef process_data(data):\n    result = handle_item(data)\n    return do_thing(result)\n\n# Good: Specific names\ndef calculate_tax(order):\n    taxable_amount = extract_taxable_items(order)\n    return apply_tax_rate(taxable_amount)\n```\n\n**Search:**\n```bash\n# Find generic names\ngrep -rn \"process\\|handle\\|manage\\|do_\\|data\\|item\\|thing\" src/\n```\n\n**3. Hidden Fragility:**\n```python\n# Bad: Silent failure\ntry:\n    critical_operation()\nexcept Exception:\n    pass  # Swallowed error\n\n# Bad: Implicit coupling\nglobal_state = {}  # Hidden dependency\n\n# Bad: Magic values\nif status == 42:  # What does 42 mean?\n```\n\n**Search:**\n```bash\n# Find bare except\ngrep -rn \"except:\" src/\n\n# Find global state\ngrep -rn \"^[A-Z_]\\+ = \" src/\n\n# Find magic numbers\ngrep -rn \"if.*== [0-9]\\+\" src/\n```\n\n**4. Hallucinated Dependencies:**\n```python\n# Bad: Assuming non-existent methods\nuser.auto_validate()  # Does this exist?\ncache.smart_invalidate()  # What does \"smart\" mean?\n\n# Bad: Imaginary patterns\n@auto_retry  # Not in codebase\n@cache_result  # Decorator doesn't exist\n```\n\n**Verification:**\n```bash\n# Check decorator existence\ngrep -r \"^def auto_retry\\|^class auto_retry\" src/\n\n# Verify method definitions\ngrep -r \"def auto_validate\" src/\n```\n\n## Guardrails for AI Assistance\n\n### Evidence-Based Critiques\n\n**Required:**\n- File paths\n- Line numbers\n- Actual code snippets\n- Measured metrics\n\n**Forbidden:**\n- \"Looks like...\"\n- \"Probably should...\"\n- \"Best practice is...\"\n- \"Generally we...\"\n\n### Trade-Off Statements\n\n**Good:**\n```\nOption A: PostgreSQL\n+ Proven reliability, ACID compliance\n+ Team expertise\n- Higher hosting cost\n- Vertical scaling limits\n\nOption B: DynamoDB\n+ Horizontal scalability\n+ Lower latency\n- Team learning curve\n- Complex query limitations\n```\n\n**Bad:**\n```\n\"PostgreSQL is better for this use case.\"\n\"DynamoDB would be more scalable.\"\n```\n\n### Replace Hollow Phrases\n\n| Hollow Phrase | Replace With |\n|--------------|--------------|\n| \"Clean code\" | Specific principle (SRP, LoD) |\n| \"Best practice\" | Cited guideline or measured benefit |\n| \"Should be\" | Evidence-based observation |\n| \"More maintainable\" | Specific metric (coupling, complexity) |\n| \"Industry standard\" | Named standard (RESTful, OAuth 2.0) |\n\n## Security Checks\n\n### Input Validation\n\n**1. Boundary Validation:**\n```python\n# Check: All external inputs validated\n@validate_input\ndef create_user(email: str, age: int):\n    if not is_valid_email(email):\n        raise ValidationError(\"Invalid email\")\n    if not (0 < age < 150):\n        raise ValidationError(\"Invalid age\")\n```\n\n**Search:**\n```bash\n# Find unvalidated endpoints\ngrep -rn \"@app.route\\|@api\" src/ -A 10 | grep -v \"validate\\|check\\|verify\"\n```\n\n**2. SQL Injection Prevention:**\n```python\n# Bad\nquery = f\"SELECT * FROM users WHERE id = {user_id}\"\n\n# Good\nquery = \"SELECT * FROM users WHERE id = ?\"\ncursor.execute(query, (user_id,))\n```\n\n**Search:**\n```bash\n# Find string interpolation in SQL\ngrep -rn \"f\\\".*SELECT\\|\\\".*SELECT.*{\" src/\n```\n\n**3. XSS Prevention:**\n```python\n# Check for auto-escaping\n# Framework default: Flask (manual), Django (auto)\n```\n\n### Least Privilege\n\n**1. Minimum Permissions:**\n```python\n# Bad: Admin for everything\ndb_user = \"admin\"\n\n# Good: Specific roles\ndb_user = \"app_readonly\"  # For queries\ndb_user = \"app_writer\"    # For mutations\n```\n\n**2. Capability Checks:**\n```bash\n# Find permission checks\ngrep -rn \"check_permission\\|require_role\\|authorize\" src/\n```\n\n### Error Handling\n\n**1. No Sensitive Leaks:**\n```python\n# Bad\nexcept Exception as e:\n    return {\"error\": str(e)}  # May expose internals\n\n# Good\nexcept Exception as e:\n    logger.error(f\"Operation failed: {e}\")\n    return {\"error\": \"Operation failed\"}\n```\n\n**2. Proper Logging:**\n```bash\n# Check logging coverage\ngrep -rn \"logger\\.\\(error\\|warning\\)\" src/ | wc -l\n```\n\n## Performance Checks\n\n### Performance Budgets\n\nDefine limits:\n```yaml\nresponse_time:\n  p50: 100ms\n  p95: 500ms\n  p99: 1000ms\n\ndatabase_queries:\n  max_per_request: 10\n\nmemory:\n  max_heap: 512MB\n```\n\n### N+1 Query Detection\n\n```python\n# Bad: N+1 queries\nfor user in users:\n    user.get_orders()  # Query per user\n\n# Good: Eager loading\nusers = User.query.options(joinedload('orders')).all()\n```\n\n**Search:**\n```bash\n# Find potential N+1\ngrep -rn \"for.*in.*:\" src/ -A 3 | grep \"get_\\|fetch_\\|find_\"\n```\n\n### Caching Strategy\n\n**Check for:**\n- Cache key design\n- TTL configuration\n- Invalidation strategy\n- Cache stampede prevention\n\n```bash\n# Find caching usage\ngrep -rn \"@cache\\|cache.get\\|cache.set\" src/\n```\n\n### Index Coverage\n\n```bash\n# Check migrations for indexes\ngrep -r \"CREATE INDEX\\|add_index\" migrations/\n\n# Find missing indexes (slow queries)\n# Review query logs, not static analysis\n```\n\n## Integration with Architecture Review\n\nUse this module during Step 4 (Principle Checks):\n1. Run LoD detection searches\n2. Check for anti-slop patterns\n3. Verify AI assistance guardrails\n4. Execute security checks\n5. Validate performance budgets\n6. Document violations with evidence\n7. Recommend specific fixes with file/line references\n\nFile v1.9.16:skill-card.md\n\n## Description: <br>\nAssesses architecture decisions, ADR compliance, and coupling. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[athola](https://clawhub.ai/user/athola) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and engineers use this skill to review architecture changes before merge, including ADR compliance, module coupling, design invariants, security and performance checks, and follow-up actions. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Broad trigger wording may cause the skill to activate during general design or pattern discussions. <br>\nMitigation: Narrow the trigger wording or invoke the skill explicitly when architecture review is intended. <br>\nRisk: Architecture recommendations can be incorrect if the agent silently revises existing design invariants. <br>\nMitigation: Use the skill's invariant-conflict workflow to present preserve, layer, and revise options and escalate the final decision to a human reviewer. <br>\n\n\n## Reference(s): <br>\n- [Pensive plugin homepage](https://github.com/athola/claude-night-market/tree/master/plugins/pensive) <br>\n- [ADR Audit Module](modules/adr-audit.md) <br>\n- [Coupling Analysis Module](modules/coupling-analysis.md) <br>\n- [Principle Checks Module](modules/principle-checks.md) <br>\n- [FPF Architecture Review Methodology](modules/fpf-methodology.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Analysis, Markdown, Shell commands, Guidance] <br>\n**Output Format:** [Markdown with inline shell commands, checklists, diagrams, findings, recommendations, and follow-up actions] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [May include approve, approve-with-actions, or block recommendations for architecture reviews.] <br>\n\n## Skill Version(s): <br>\n1.9.16 (source: release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.9.14: 7 files, 15461 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), skill-card.md (2590b), SKILL.md (7846b), _meta.json (150b)\n\nFile v1.9.14:SKILL.md\n\n---\nname: architecture-review\ndescription: Assesses architecture decisions, ADR compliance, and coupling\nversion: 1.9.8\ntriggers:\n  - architecture\n  - design\n  - adr\n  - coupling\n  - patterns\n  - principles\n  - evaluating design changes or validating structural decisions before merging\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/athola/claude-night-market/tree/master/plugins/pensive\", \"emoji\": \"\\ud83c\\udfd7\\ufe0f\", \"requires\": {\"config\": [\"night-market.pensive:shared\", \"night-market.imbue:proof-of-work\", \"night-market.imbue:diff-analysis/modules/risk-assessment-framework\"]}}}\nsource: claude-night-market\nsource_plugin: pensive\n---\n\n> **Night Market Skill** — ported from [claude-night-market/pensive](https://github.com/athola/claude-night-market/tree/master/plugins/pensive). For the full experience with agents, hooks, and commands, install the Claude Code plugin.\n\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [When to Use](#when-to-use)\n- [Progressive Loading](#progressive-loading)\n- [Required TodoWrite Items](#required-todowrite-items)\n- [Workflow](#workflow)\n- [Step 1: Establish Context (`arch-review:context-established`)](#step-1:-establish-context-(arch-review:context-established))\n- [Step 2: ADR Audit (`arch-review:adr-audit`)](#step-2:-adr-audit-(arch-review:adr-audit))\n- [Step 3: Interaction Mapping (`arch-review:interaction-mapping`)](#step-3:-interaction-mapping-(arch-review:interaction-mapping))\n- [Step 4: Principle Checks (`arch-review:principle-checks`)](#step-4:-principle-checks-(arch-review:principle-checks))\n- [Step 5: Risks and Actions (`arch-review:risks-actions`)](#step-5:-risks-and-actions-(arch-review:risks-actions))\n- [Testing](#testing)\n\n## Testing\n\nRun `pytest plugins/pensive/tests/skills/test_architecture_review.py` to verify review logic.\n- [Architecture Principles Checklist](#architecture-principles-checklist)\n- [Coupling](#coupling)\n- [Cohesion](#cohesion)\n- [Layering](#layering)\n- [Evolution](#evolution)\n\n\n# Architecture Review Workflow\n\nArchitecture assessment against ADRs and design principles.\n\n## Quick Start\n\n```bash\n/architecture-review\n```\n\n## When To Use\n\n- Approving reimplementations.\n- Large-scale refactoring reviews.\n- System design changes.\n- New module/service introduction.\n- Dependency restructuring.\n\n## When NOT To Use\n\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n\n## Progressive Loading\n\nLoad modules based on review scope:\n\n- **`modules/adr-audit.md`** (~400 tokens): ADR verification and documentation.\n- **`modules/coupling-analysis.md`** (~450 tokens): Dependency analysis and boundary violations.\n- **`modules/principle-checks.md`** (~500 tokens): Code quality, security, and performance.\n- **`modules/fpf-methodology.md`** (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.\n\nLoad all modules for full reviews. For focused reviews, load only relevant modules.\n\n## Required TodoWrite Items\n\n1. `arch-review:context-established`: Repository, branch, motivation.\n2. `arch-review:adr-audit`: ADR verification and new ADR needs.\n3. `arch-review:interaction-mapping`: Module coupling analysis.\n4. `arch-review:invariant-check`: Invariant conflict detection and 3-option analysis.\n5. `arch-review:principle-checks`: LoD, security, performance.\n6. `arch-review:risks-actions`: Recommendation and follow-ups.\n\n## Workflow\n\n### Step 1: Establish Context (`arch-review:context-established`)\n\nConfirm repository and branch:\n```bash\npwd\ngit status -sb\n```\n\nDocument:\n- Feature/bug/epic motivating review.\n- Affected subsystems.\n- Architectural intent from README/docs.\n- Design trade-off assumptions.\n\n### Step 2: ADR Audit (`arch-review:adr-audit`)\n\n**Load: `modules/adr-audit.md`**\n\n- Locate ADRs in project.\n- Verify required sections.\n- Check status flow.\n- Confirm immutability compliance.\n- Flag need for new ADRs.\n\n### Step 3: Interaction Mapping (`arch-review:interaction-mapping`)\n\n**Load: `modules/coupling-analysis.md`**\n\n- Diagram before/after module interactions.\n- Verify composition boundaries.\n- Check data ownership clarity.\n- Validate dependency flow direction.\n- Identify coupling violations.\n\n### Step 3.5: Invariant Conflict Detection (`arch-review:invariant-check`)\n\nBefore checking principles, identify whether the changes\nconflict with existing design invariants. This is the\nhighest-judgment step in architecture review — models\nget this wrong more often than any other call.\n\n**Identify existing invariants:**\n\n1. Scan ADRs for recorded decisions still in \"accepted\"\n   status\n2. Check module boundaries (are imports crossing layers\n   that previously didn't?)\n3. Check data flow direction (does data now flow in a\n   new direction?)\n4. Check API contracts (are public interfaces changing\n   shape?)\n5. Check structural patterns (is a new pattern being\n   introduced alongside an existing one?)\n\n```bash\n# Detect boundary crossings in changed files\ngit diff --name-only | while read f; do\n  head -20 \"$f\" 2>/dev/null | rg \"^(import|from|use |require)\" || true\ndone\n```\n\n**When a conflict is detected:**\n\nDo NOT recommend a resolution. Present the three options\nand escalate to human judgment:\n\n| Option | When Right | When Wrong |\n|--------|------------|------------|\n| **Preserve invariant** (reject feature) | Invariant simplifies many things; feature is marginal | Feature is genuinely needed and invariant is stale |\n| **Layer on top** (add inelegantly) | Feature is needed; invariant still valuable; imperfection is OK | Layering creates a maintenance trap that will compound |\n| **Revise invariant** (change the design) | Genuine new learning invalidates the original reasoning | You're \"cleaning up\" a decision you don't fully understand |\n\n**Output format:**\n\n```markdown\n### Invariant Conflicts\n\n[I1] **[Invariant name]** — [what decision it represents]\n- **Conflict**: [what change clashes]\n- **Options**: Preserve / Layer / Revise\n- **Recommendation**: ESCALATE TO HUMAN\n- **Risk if wrong**: [what compounds]\n```\n\n**Why this matters:** Bad invariant decisions compound.\nAfter a few wrong calls the codebase becomes\nunsalvageable. This is a judgment problem, not a context\nproblem — the agent should surface it, not solve it.\n\n### Step 4: Principle Checks (`arch-review:principle-checks`)\n\n**Load: `modules/principle-checks.md`**\n\n- Law of Demeter.\n- Anti-slop patterns.\n- Security (input validation, least privilege).\n- Performance (N+1 queries, caching).\n\n### Step 5: Risks and Actions (`arch-review:risks-actions`)\n\nSummarize using `imbue:diff-analysis/modules/risk-assessment-framework`:\n- Current vs proposed architecture.\n- Business impact.\n- Technical debt implications.\n\nList follow-ups with owners and dates.\n\nProvide recommendation:\n- **Approve**: Architecture sound.\n- **Approve with actions**: Minor issues to address.\n- **Block**: Fundamental problems requiring redesign.\n\n## Architecture Principles Checklist\n\n### Coupling\n- [ ] Dependencies follow defined boundaries.\n- [ ] No circular dependencies.\n- [ ] Extension points used properly.\n- [ ] Abstractions don't leak.\n\n### Cohesion\n- [ ] Related functionality grouped.\n- [ ] Single responsibility per module.\n- [ ] Clear module purposes.\n\n### Layering\n- [ ] Layers have clear responsibilities.\n- [ ] Dependencies flow downward.\n- [ ] No layer bypassing.\n\n### Invariants\n- [ ] Existing design invariants identified.\n- [ ] Conflicts between changes and invariants surfaced.\n- [ ] Three-option analysis (preserve/layer/revise) presented.\n- [ ] Invariant changes escalated to human judgment.\n- [ ] No silent invariant revisions in the diff.\n\n### Evolution\n- [ ] Changes are reversible.\n- [ ] Migration paths are clear.\n- [ ] ADRs document decisions.\n\nFile v1.9.14:_meta.json\n\n{\n  \"ownerId\": \"kn7d107jg9jv602h9ytsegydq184a42s\",\n  \"slug\": \"nm-pensive-architecture-review\",\n  \"version\": \"1.9.14\",\n  \"publishedAt\": 1782842625240\n}\n\nFile v1.9.14:modules/adr-audit.md\n\n---\nname: adr-audit\ndescription: Architecture Decision Record audit patterns and verification workflows\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [adr, documentation, governance, decisions]\ncomplexity: intermediate\nestimated_tokens: 400\n---\n\n# ADR Audit Module\n\ndetailed ADR discovery, validation, and governance patterns.\n\n## ADR Location Patterns\n\nCommon ADR locations by project type:\n\n```bash\n# Standard locations\nwiki/architecture/\ndocs/adr/\ndocs/decisions/\narchitecture/decisions/\n.adr/\n\n# Search pattern\nfind . -type f -name \"*ADR*\" -o -name \"*decision*\" | grep -E \"\\.(md|txt)$\"\n```\n\n## Required ADR Sections\n\nEvery ADR must include:\n\n### 1. Title\nClear, specific decision statement:\n- \"Use PostgreSQL for primary datastore\"\n- \"Adopt hexagonal architecture pattern\"\n- \"Implement JWT-based authentication\"\n\n### 2. Status\nMust follow strict progression:\n```\nProposed → Reviewed → Accepted\n                    ↓\n              Superseded (when invalidated)\n```\n\n**Rules:**\n- Status changes are append-only\n- Date each status transition\n- Never delete/modify accepted ADRs\n- Use \"Superseded by ADR-XXX\" to replace\n\n### 3. Context\nDocument the forces at play:\n- Business requirements\n- Technical constraints\n- Team capabilities\n- Timeline pressures\n- Existing architecture\n\n### 4. Decision\nThe \"we will...\" statement:\n- Clear action chosen\n- Implementation approach\n- Key design choices\n\n### 5. Alternatives Considered\nFor each alternative:\n- Description\n- Pros/cons\n- Why rejected\n\nMinimum 2 alternatives required.\n\n### 6. Consequences\n\n**Positive:**\n- Benefits gained\n- Problems solved\n- Capabilities enabled\n\n**Negative:**\n- Trade-offs accepted\n- Technical debt incurred\n- Complexity added\n\n**Neutral:**\n- Changes required\n- Migration steps\n- Training needs\n\n### 7. Metadata\n```yaml\nDate: YYYY-MM-DD\nAuthor: [name]\nStatus: [status]\nSupersedes: [ADR-XXX] (if applicable)\nSuperseded-by: [ADR-XXX] (if applicable)\n```\n\n## Status Flow Verification\n\n### Valid Transitions\n- Proposed → Reviewed\n- Reviewed → Accepted\n- Reviewed → Rejected\n- Accepted → Superseded (via new ADR only)\n\n### Invalid Transitions\n- Proposed -> Accepted (skip review)\n- Accepted -> Rejected (use Superseded)\n- Superseded -> Accepted (immutable)\n\n## Immutability Rules\n\n**Once Accepted:**\n1. **Never modify** decision content\n2. **Never change** consequences\n3. **Never delete** the ADR\n4. **Only append** status changes\n\n**To Replace:**\n1. Create new ADR with superseding decision\n2. Add \"Supersedes: ADR-XXX\" to new ADR\n3. Add \"Superseded-by: ADR-YYY\" to old ADR\n4. Update old ADR status to \"Superseded\"\n\n## Audit Workflow\n\n### 1. Locate All ADRs\n```bash\n# Find ADR directory\nls -la docs/adr/ wiki/architecture/ 2>/dev/null\n\n# Count ADRs\nfind . -path \"*/adr/*.md\" -o -path \"*/decisions/*.md\" | wc -l\n```\n\n### 2. Verify Structure\nFor each ADR:\n- [ ] Has all required sections\n- [ ] Status follows valid flow\n- [ ] Dates are present\n- [ ] Alternatives documented (≥2)\n- [ ] Consequences specified\n\n### 3. Check References\n```bash\n# Find ADR references in code\ngrep -r \"ADR-[0-9]\" --include=\"*.md\" --include=\"*.py\" --include=\"*.js\"\n\n# Verify backlinks\ngrep \"Superseded-by\" docs/adr/*.md\n```\n\n### 4. Flag Issues\nCommon problems:\n- Missing sections\n- Invalid status transitions\n- Modified accepted ADRs\n- Missing supersession links\n- Insufficient alternatives\n\n## New ADR Requirements\n\nFlag need for new ADR when:\n- Introducing new architectural pattern\n- Changing core technology\n- Modifying system boundaries\n- Adding external dependencies\n- Changing security model\n\n**Before implementation:**\n1. Draft ADR with all sections\n2. Set status: Proposed\n3. Request review\n4. Update to Reviewed\n5. Gain approval → Accepted\n6. Then proceed with implementation\n\n## Integration with Architecture Review\n\nUse this module during Step 2 (ADR Audit):\n1. Locate ADRs using patterns\n2. Verify structure completeness\n3. Check status flow validity\n4. Confirm immutability compliance\n5. Identify missing ADRs for current work\n6. Draft new ADRs if needed\n\nFile v1.9.14:modules/coupling-analysis.md\n\n---\nname: coupling-analysis\ndescription: Interaction mapping, composition boundaries, and dependency flow analysis\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [coupling, dependencies, composition, boundaries, modularity]\ncomplexity: advanced\nestimated_tokens: 450\n---\n\n# Coupling Analysis Module\n\nSystematic analysis of module interactions, boundaries, and dependency flows.\n\n## Interaction Mapping Patterns\n\n### Visual Representation\n\nCreate before/after diagrams:\n\n```\nBefore:\n┌─────────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│Module B │────▶│ Database │\n└─────────┘     └─────────┘     └──────────┘\n\nAfter:\n┌─────────┐     ┌───────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│ Cache │────▶│Module B │────▶│ Database │\n└─────────┘     └───────┘     └─────────┘     └──────────┘\n```\n\n### Dependency Graph Tools\n\n```bash\n# Python: Generate import graph\npydeps --max-bacon=2 --cluster src/\n\n# TypeScript: Analyze module dependencies\nmadge --circular --extensions ts src/\n\n# Generic: Find direct dependencies\ngrep -r \"import\\|require\\|from\" src/ | cut -d: -f1 | sort | uniq -c\n```\n\n## Composition Boundaries\n\n### Boundary Definition\n\nClear boundaries have:\n1. **Explicit interfaces** - Published contracts\n2. **Data ownership** - Single source of truth\n3. **Encapsulation** - Hidden implementation\n4. **Stability** - Minimal breaking changes\n\n### Boundary Types\n\n**Module Boundaries:**\n```\n┌──────────────────────────┐\n│   Public API             │\n├──────────────────────────┤\n│   Internal Logic         │\n│   (implementation)       │\n└──────────────────────────┘\n```\n\n**Layer Boundaries:**\n```\n┌──────────────────────────┐\n│   Presentation Layer     │ ← HTTP/UI\n├──────────────────────────┤\n│   Application Layer      │ ← Business Logic\n├──────────────────────────┤\n│   Domain Layer           │ ← Core Models\n├──────────────────────────┤\n│   Infrastructure Layer   │ ← Database/External\n└──────────────────────────┘\n```\n\n**Service Boundaries:**\n```\nService A          Service B\n┌────────┐        ┌────────┐\n│  API   │◀──────▶│  API   │\n├────────┤        ├────────┤\n│  DB A  │        │  DB B  │\n└────────┘        └────────┘\n```\n\n### Boundary Violations\n\n**Ad-hoc Reach-ins:**\n```python\n# Bad: Reaching through module boundary\nuser.profile.settings.theme.get_color()\n\n# Good: Ask for what you need\nuser.get_theme_color()\n```\n\n**Layering Violations:**\n```python\n# Bad: Domain layer accessing infrastructure\nclass Order:\n    def save(self):\n        db.execute(\"INSERT INTO orders...\")\n\n# Good: Infrastructure handles persistence\nclass OrderRepository:\n    def save(self, order: Order):\n        db.execute(\"INSERT INTO orders...\")\n```\n\n## Data Ownership Analysis\n\n### Single Owner Principle\n\nEach data entity has exactly one authoritative owner:\n\n```\nUser Data:\n├── Auth Service (owner: credentials)\n├── Profile Service (owner: profile data)\n└── Analytics Service (consumer: read-only)\n```\n\n### Ownership Violations\n\n**Multiple Writers:**\n```python\n# Bad: Two services modify same data\nauth_service.update_user_email()\nprofile_service.update_user_email()\n\n# Good: Single owner\nprofile_service.update_email()  # Publishes event\nauth_service.handle_email_changed()  # Subscribes to event\n```\n\n**Ownership Leaks:**\n```python\n# Bad: Exposing internal structure\ndef get_user():\n    return user_database_model\n\n# Good: Return boundary type\ndef get_user():\n    return UserDTO(id=..., name=...)\n```\n\n## Dependency Flow Checking\n\n### Expected Flow Patterns\n\n**Layered Architecture:**\n```\nPresentation → Application → Domain → Infrastructure\n     ↓              ↓           ↓            ↓\n  (no reverse dependencies allowed)\n```\n\n**Hexagonal Architecture:**\n```\n     ┌─────────────┐\n     │   Domain    │ ← Core (no dependencies)\n     └──────┬──────┘\n            │\n  ┌─────────┴─────────┐\n  │   Application     │ ← Orchestration\n  └────────┬──────────┘\n           │\n  ┌────────┴─────────┐\n  │   Adapters       │ ← External interfaces\n  └──────────────────┘\n```\n\n### Circular Dependency Detection\n\n```bash\n# Python\npydeps --show-cycles src/\n\n# JavaScript/TypeScript\nmadge --circular src/\n\n# Manual check\ngrep -r \"from.*import\" src/ | # Extract all imports\n  python -c \"\nimport sys\nfrom collections import defaultdict\n\ngraph = defaultdict(set)\nfor line in sys.stdin:\n    # Parse: file imports module\n    # Build graph, detect cycles\n\"\n```\n\n### Dependency Metrics\n\n**Afferent Coupling (Ca):**\nNumber of modules that depend on this module.\n- High Ca = Stable (many dependents)\n\n**Efferent Coupling (Ce):**\nNumber of modules this module depends on.\n- High Ce = Unstable (many dependencies)\n\n**Instability (I):**\n```\nI = Ce / (Ca + Ce)\n```\n- I = 0: Maximally stable\n- I = 1: Maximally unstable\n\n### Ideal Patterns\n\n**Stable Abstractions:**\n- Core domain: Low I (stable)\n- Infrastructure: High I (unstable, replaceable)\n\n**Dependency Direction:**\n```\nUnstable → Stable\n(changing) depends on (stable)\n```\n\n## Side Effects Analysis\n\n### Side Effect Categories\n\n**1. State Mutations:**\n```python\n# Track mutations\ndef process_order(order):\n    order.status = \"PROCESSED\"  # Mutation\n    notify_customer(order)       # Side effect\n    log_event(order)            # Side effect\n```\n\n**2. External I/O:**\n- Database writes\n- API calls\n- File operations\n- Message queue publishing\n\n**3. Timing Dependencies:**\n- Caching\n- Rate limiting\n- Session management\n\n### Containment Strategies\n\n**Command-Query Separation:**\n```python\n# Query: No side effects\ndef get_order_total(order): -> Decimal\n\n# Command: Mutations allowed\ndef place_order(order) -> None\n```\n\n**Effect Tracking:**\n```python\n# Explicit effect types\nEffect = Database | API | Cache | Event\n\ndef process_payment(order) -> tuple[Result, list[Effect]]:\n    effects = []\n    # Track all effects\n    return result, effects\n```\n\n## Cross-Boundary Dependencies\n\n### Allowed Patterns\n\n**1. Events:**\n```python\n# Service A publishes\nevent_bus.publish(UserCreated(user_id))\n\n# Service B subscribes\n@subscribe(UserCreated)\ndef handle_user_created(event):\n    # React independently\n```\n\n**2. Shared Kernel:**\n```python\n# Common domain types\nfrom shared.types import Money, UserId, Email\n```\n\n**3. Published APIs:**\n```python\n# Service B calls Service A's API\nresponse = service_a_client.get_user(user_id)\n```\n\n### Forbidden Patterns\n\n**1. Shared Database:**\n```python\n# Bad: Direct database access across services\nuser_db.query(\"SELECT * FROM users\")  # From order service\n```\n\n**2. Implementation Sharing:**\n```python\n# Bad: Importing internal modules\nfrom service_a.internal.helpers import format_date\n```\n\n## Integration with Architecture Review\n\nUse this module during Step 3 (Interaction Mapping):\n1. Map all module interactions (before/after)\n2. Verify composition boundaries\n3. Check data ownership clarity\n4. Validate dependency flow direction\n5. Detect circular dependencies\n6. Identify coupling violations\n7. Analyze side effect containment\n\nFile v1.9.14:modules/fpf-methodology.md\n\n# FPF Architecture Review Methodology\n\nConduct architecture reviews using the FPF (Functional, Practical, Foundation) methodology, evaluating codebases through three complementary perspectives.\n\n## Philosophy\n\nArchitecture reviews should be systematic and multi-dimensional. FPF provides three lenses:\n- **Functional**: What the system does (capabilities, behaviors)\n- **Practical**: How well it works (performance, usability)\n- **Foundation**: What it's built on (principles, patterns)\n\n## Quick Start\n\n```bash\n# Full FPF review\n/architecture-review --methodology fpf\n\n# Specific perspective\n/architecture-review --perspective functional\n/architecture-review --perspective practical\n/architecture-review --perspective foundation\n```\n\n## The Three Perspectives\n\n### 1. Functional Perspective\n\n**Question:** What does this system do?\n\n**Evaluates:**\n- Feature completeness\n- Capability coverage\n- Behavior correctness\n- Integration points\n\n**Outputs:**\n- Feature inventory\n- Capability gaps\n- Behavior anomalies\n\n### 2. Practical Perspective\n\n**Question:** How well does this system work?\n\n**Evaluates:**\n- Performance characteristics\n- Usability patterns\n- Operational concerns\n- Scalability considerations\n\n**Outputs:**\n- Performance assessment\n- Usability issues\n- Operational recommendations\n\n### 3. Foundation Perspective\n\n**Question:** What is this system built on?\n\n**Evaluates:**\n- Architectural patterns\n- Design principles\n- Code quality\n- Technical debt\n\n**Outputs:**\n- Pattern analysis\n- Principle adherence\n- Debt inventory\n\n## FPF Workflow\n\n### Phase 1: Discovery\n1. Scan codebase structure - Identify components, modules, layers\n2. Map dependencies - Internal and external relationships\n3. Identify entry points - Public APIs, commands, interfaces\n\n### Phase 2: Functional Analysis\n1. Inventory features - What capabilities exist\n2. Trace behaviors - How features work end-to-end\n3. Identify gaps - Missing or incomplete functionality\n\n### Phase 3: Practical Analysis\n1. Assess performance - Latency, throughput, resource usage\n2. Evaluate usability - Developer experience, API design\n3. Check operations - Logging, monitoring, error handling\n\n### Phase 4: Foundation Analysis\n1. Pattern recognition - What patterns are used\n2. Principle check - SOLID, DRY, KISS adherence\n3. Debt assessment - Technical debt inventory\n\n### Phase 5: Synthesis\n1. Cross-reference findings - Connect issues across perspectives\n2. Prioritize recommendations - Based on impact and effort\n3. Generate report - Structured findings and actions\n\n## FPF Report Template\n\n```markdown\n# FPF Architecture Review: [Project/Component]\n\n**Date:** [DATE]\n**Scope:** [what was reviewed]\n\n## Executive Summary\n[2-3 sentence overview of findings]\n\n## Functional Perspective\n### Features Inventory\n| Feature | Status | Notes |\n|---------|--------|-------|\n| [Feature 1] | Complete | - |\n\n### Capability Gaps\n1. [Gap 1] - [Impact]\n\n## Practical Perspective\n### Performance Assessment\n| Metric | Current | Target | Status |\n|--------|---------|--------|--------|\n| [Metric 1] | [value] | [target] | PASS/FAIL |\n\n## Foundation Perspective\n### Pattern Analysis\n| Pattern | Usage | Assessment |\n|---------|-------|------------|\n| [Pattern 1] | [where used] | Appropriate/Problematic |\n\n### Technical Debt\n| Item | Severity | Effort | Priority |\n|------|----------|--------|----------|\n| [Debt 1] | High | Medium | P1 |\n\n## Recommendations\n### High Priority\n1. **[Recommendation]** - Impact: [what improves] - Effort: [estimate]\n```\n\n## Configuration\n\n```yaml\nperspectives:\n  functional:\n    enabled: true\n    depth: \"full\"  # full, summary\n  practical:\n    enabled: true\n    depth: \"full\"\n  foundation:\n    enabled: true\n    depth: \"full\"\n```\n\n## Guardrails\n\n1. **Scope boundaries** - Stay within configured scope\n2. **Evidence-based** - Every finding needs supporting evidence\n3. **Actionable output** - Recommendations must be actionable\n4. **Balanced perspectives** - Don't over-index on one perspective\n\n## References\n\n- [FPF Framework](https://github.com/ailev/FPF) - Original methodology\n- [quint-code](https://github.com/m0n0x41d/quint-code) - Heavy implementation (this skill is lighter)\n\nFile v1.9.14:modules/principle-checks.md\n\n---\nname: principle-checks\ndescription: Law of Demeter, anti-slop patterns, AI guardrails, and security/performance checks\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [principles, demeter, anti-patterns, security, performance, quality]\ncomplexity: advanced\nestimated_tokens: 500\n---\n\n# Principle Checks Module\n\nSystematic verification of architectural principles, anti-patterns, and quality attributes.\n\n## Law of Demeter (LoD)\n\n### The Principle\n\n\"Talk to friends, not to strangers.\"\n\nAn object should only call methods on:\n1. Itself\n2. Its parameters\n3. Objects it creates\n4. Its direct components\n\n### Train Wreck Detection\n\n**Anti-pattern:**\n```python\n# Bad: Chain of calls\ncustomer.get_address().get_city().get_postal_code()\n\n# Bad: Multiple dereferences\norder.customer.billing_address.street\n\n# Bad: Deep navigation\ncontext.request.session.user.preferences.theme\n```\n\n**Search patterns:**\n```bash\n# Python\ngrep -rn '\\.\\w\\+(\\)\\.\\w\\+(\\)\\.\\w\\+(' src/\n\n# JavaScript/TypeScript\ngrep -rn '\\.\\w\\+\\.\\w\\+\\.\\w\\+' src/ --include=\"*.js\" --include=\"*.ts\"\n\n# Count violations\ngrep -r '\\.\\w\\+\\.\\w\\+\\.\\w\\+' src/ | wc -l\n```\n\n### Refactoring Strategies\n\n**Strategy 1: Tell, Don't Ask**\n```python\n# Before\nif customer.get_address().get_country() == \"US\":\n    apply_us_tax()\n\n# After\nif customer.is_in_country(\"US\"):\n    apply_us_tax()\n```\n\n**Strategy 2: Move Logic to Owner**\n```python\n# Before\npostal_code = customer.get_address().get_postal_code()\nregion = lookup_region(postal_code)\n\n# After\nregion = customer.get_region()  # Address logic inside Customer\n```\n\n**Strategy 3: Introduce Facade**\n```python\n# Before\nconfig.get_database().get_connection_pool().get_connection()\n\n# After\nconfig.get_database_connection()  # Facade hides complexity\n```\n\n## Anti-Slop Checks\n\n### What is \"Slop\"?\n\nCode that appears professional but lacks substance:\n- Generic naming\n- Overengineering\n- Cargo cult patterns\n- Hallucinated dependencies\n- Hollow abstractions\n\n### Detection Patterns\n\n**1. Overengineering Red Flags:**\n```python\n# Bad: Unnecessary abstraction layers\nclass UserFactoryFactory:\n    def create_user_factory(self):\n        return UserFactory()\n\n# Bad: Premature generalization\nclass AbstractBaseEntityManagerInterface:\n    pass\n```\n\n**Search:**\n```bash\n# Find \"Abstract\" overuse\ngrep -r \"class Abstract\" src/ | wc -l\n\n# Find \"Manager\" bloat\ngrep -r \"Manager\\|Handler\\|Processor\" src/ --include=\"*.py\"\n\n# Find deep inheritance\ngrep -A 5 \"class.*:\" src/**/*.py | grep \"    class\"\n```\n\n**2. Generic Naming:**\n```python\n# Bad: Non-descriptive names\ndef process_data(data):\n    result = handle_item(data)\n    return do_thing(result)\n\n# Good: Specific names\ndef calculate_tax(order):\n    taxable_amount = extract_taxable_items(order)\n    return apply_tax_rate(taxable_amount)\n```\n\n**Search:**\n```bash\n# Find generic names\ngrep -rn \"process\\|handle\\|manage\\|do_\\|data\\|item\\|thing\" src/\n```\n\n**3. Hidden Fragility:**\n```python\n# Bad: Silent failure\ntry:\n    critical_operation()\nexcept Exception:\n    pass  # Swallowed error\n\n# Bad: Implicit coupling\nglobal_state = {}  # Hidden dependency\n\n# Bad: Magic values\nif status == 42:  # What does 42 mean?\n```\n\n**Search:**\n```bash\n# Find bare except\ngrep -rn \"except:\" src/\n\n# Find global state\ngrep -rn \"^[A-Z_]\\+ = \" src/\n\n# Find magic numbers\ngrep -rn \"if.*== [0-9]\\+\" src/\n```\n\n**4. Hallucinated Dependencies:**\n```python\n# Bad: Assuming non-existent methods\nuser.auto_validate()  # Does this exist?\ncache.smart_invalidate()  # What does \"smart\" mean?\n\n# Bad: Imaginary patterns\n@auto_retry  # Not in codebase\n@cache_result  # Decorator doesn't exist\n```\n\n**Verification:**\n```bash\n# Check decorator existence\ngrep -r \"^def auto_retry\\|^class auto_retry\" src/\n\n# Verify method definitions\ngrep -r \"def auto_validate\" src/\n```\n\n## Guardrails for AI Assistance\n\n### Evidence-Based Critiques\n\n**Required:**\n- File paths\n- Line numbers\n- Actual code snippets\n- Measured metrics\n\n**Forbidden:**\n- \"Looks like...\"\n- \"Probably should...\"\n- \"Best practice is...\"\n- \"Generally we...\"\n\n### Trade-Off Statements\n\n**Good:**\n```\nOption A: PostgreSQL\n+ Proven reliability, ACID compliance\n+ Team expertise\n- Higher hosting cost\n- Vertical scaling limits\n\nOption B: DynamoDB\n+ Horizontal scalability\n+ Lower latency\n- Team learning curve\n- Complex query limitations\n```\n\n**Bad:**\n```\n\"PostgreSQL is better for this use case.\"\n\"DynamoDB would be more scalable.\"\n```\n\n### Replace Hollow Phrases\n\n| Hollow Phrase | Replace With |\n|--------------|--------------|\n| \"Clean code\" | Specific principle (SRP, LoD) |\n| \"Best practice\" | Cited guideline or measured benefit |\n| \"Should be\" | Evidence-based observation |\n| \"More maintainable\" | Specific metric (coupling, complexity) |\n| \"Industry standard\" | Named standard (RESTful, OAuth 2.0) |\n\n## Security Checks\n\n### Input Validation\n\n**1. Boundary Validation:**\n```python\n# Check: All external inputs validated\n@validate_input\ndef create_user(email: str, age: int):\n    if not is_valid_email(email):\n        raise ValidationError(\"Invalid email\")\n    if not (0 < age < 150):\n        raise ValidationError(\"Invalid age\")\n```\n\n**Search:**\n```bash\n# Find unvalidated endpoints\ngrep -rn \"@app.route\\|@api\" src/ -A 10 | grep -v \"validate\\|check\\|verify\"\n```\n\n**2. SQL Injection Prevention:**\n```python\n# Bad\nquery = f\"SELECT * FROM users WHERE id = {user_id}\"\n\n# Good\nquery = \"SELECT * FROM users WHERE id = ?\"\ncursor.execute(query, (user_id,))\n```\n\n**Search:**\n```bash\n# Find string interpolation in SQL\ngrep -rn \"f\\\".*SELECT\\|\\\".*SELECT.*{\" src/\n```\n\n**3. XSS Prevention:**\n```python\n# Check for auto-escaping\n# Framework default: Flask (manual), Django (auto)\n```\n\n### Least Privilege\n\n**1. Minimum Permissions:**\n```python\n# Bad: Admin for everything\ndb_user = \"admin\"\n\n# Good: Specific roles\ndb_user = \"app_readonly\"  # For queries\ndb_user = \"app_writer\"    # For mutations\n```\n\n**2. Capability Checks:**\n```bash\n# Find permission checks\ngrep -rn \"check_permission\\|require_role\\|authorize\" src/\n```\n\n### Error Handling\n\n**1. No Sensitive Leaks:**\n```python\n# Bad\nexcept Exception as e:\n    return {\"error\": str(e)}  # May expose internals\n\n# Good\nexcept Exception as e:\n    logger.error(f\"Operation failed: {e}\")\n    return {\"error\": \"Operation failed\"}\n```\n\n**2. Proper Logging:**\n```bash\n# Check logging coverage\ngrep -rn \"logger\\.\\(error\\|warning\\)\" src/ | wc -l\n```\n\n## Performance Checks\n\n### Performance Budgets\n\nDefine limits:\n```yaml\nresponse_time:\n  p50: 100ms\n  p95: 500ms\n  p99: 1000ms\n\ndatabase_queries:\n  max_per_request: 10\n\nmemory:\n  max_heap: 512MB\n```\n\n### N+1 Query Detection\n\n```python\n# Bad: N+1 queries\nfor user in users:\n    user.get_orders()  # Query per user\n\n# Good: Eager loading\nusers = User.query.options(joinedload('orders')).all()\n```\n\n**Search:**\n```bash\n# Find potential N+1\ngrep -rn \"for.*in.*:\" src/ -A 3 | grep \"get_\\|fetch_\\|find_\"\n```\n\n### Caching Strategy\n\n**Check for:**\n- Cache key design\n- TTL configuration\n- Invalidation strategy\n- Cache stampede prevention\n\n```bash\n# Find caching usage\ngrep -rn \"@cache\\|cache.get\\|cache.set\" src/\n```\n\n### Index Coverage\n\n```bash\n# Check migrations for indexes\ngrep -r \"CREATE INDEX\\|add_index\" migrations/\n\n# Find missing indexes (slow queries)\n# Review query logs, not static analysis\n```\n\n## Integration with Architecture Review\n\nUse this module during Step 4 (Principle Checks):\n1. Run LoD detection searches\n2. Check for anti-slop patterns\n3. Verify AI assistance guardrails\n4. Execute security checks\n5. Validate performance budgets\n6. Document violations with evidence\n7. Recommend specific fixes with file/line references\n\nFile v1.9.14:skill-card.md\n\n## Description: <br>\nAssesses architecture decisions, ADR compliance, coupling, design invariants, and code quality risks. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[athola](https://clawhub.ai/user/athola) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and engineering teams use this skill to review architecture changes before merging, including ADR coverage, module coupling, boundary violations, design invariants, security, performance, and technical debt. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Broad trigger terms such as architecture, design, patterns, and principles may activate the skill when an architecture review was not intended. <br>\nMitigation: Narrow or disable triggers in environments where broad activation is disruptive, and invoke the skill explicitly for architecture and ADR review work. <br>\nRisk: Architecture findings may be misleading if the agent reviews repository files or diffs without enough project context. <br>\nMitigation: Require evidence-backed findings with file paths, line numbers, and snippets, and have maintainers review recommendations before acting on them. <br>\nRisk: The skill may surface invariant conflicts that require architectural judgment beyond automated analysis. <br>\nMitigation: Escalate preserve, layer, or revise decisions to human reviewers instead of allowing the agent to silently change architectural invariants. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/athola/skills/nm-pensive-architecture-review) <br>\n- [Pensive source homepage](https://github.com/athola/claude-night-market/tree/master/plugins/pensive) <br>\n- [FPF Framework](https://github.com/ailev/FPF) <br>\n- [quint-code](https://github.com/m0n0x41d/quint-code) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [analysis, markdown, shell commands, guidance] <br>\n**Output Format:** [Markdown with checklists, findings, diagrams, recommendations, and inline shell commands] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [May include approve, approve-with-actions, or block recommendations and follow-up actions.] <br>\n\n## Skill Version(s): <br>\n1.9.14 (source: ClawHub release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.9.13: 7 files, 15327 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), skill-card.md (2258b), SKILL.md (7846b), _meta.json (150b)\n\nFile v1.9.13:SKILL.md\n\n---\nname: architecture-review\ndescription: Assesses architecture decisions, ADR compliance, and coupling\nversion: 1.9.8\ntriggers:\n  - architecture\n  - design\n  - adr\n  - coupling\n  - patterns\n  - principles\n  - evaluating design changes or validating structural decisions before merging\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/athola/claude-night-market/tree/master/plugins/pensive\", \"emoji\": \"\\ud83c\\udfd7\\ufe0f\", \"requires\": {\"config\": [\"night-market.pensive:shared\", \"night-market.imbue:proof-of-work\", \"night-market.imbue:diff-analysis/modules/risk-assessment-framework\"]}}}\nsource: claude-night-market\nsource_plugin: pensive\n---\n\n> **Night Market Skill** — ported from [claude-night-market/pensive](https://github.com/athola/claude-night-market/tree/master/plugins/pensive). For the full experience with agents, hooks, and commands, install the Claude Code plugin.\n\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [When to Use](#when-to-use)\n- [Progressive Loading](#progressive-loading)\n- [Required TodoWrite Items](#required-todowrite-items)\n- [Workflow](#workflow)\n- [Step 1: Establish Context (`arch-review:context-established`)](#step-1:-establish-context-(arch-review:context-established))\n- [Step 2: ADR Audit (`arch-review:adr-audit`)](#step-2:-adr-audit-(arch-review:adr-audit))\n- [Step 3: Interaction Mapping (`arch-review:interaction-mapping`)](#step-3:-interaction-mapping-(arch-review:interaction-mapping))\n- [Step 4: Principle Checks (`arch-review:principle-checks`)](#step-4:-principle-checks-(arch-review:principle-checks))\n- [Step 5: Risks and Actions (`arch-review:risks-actions`)](#step-5:-risks-and-actions-(arch-review:risks-actions))\n- [Testing](#testing)\n\n## Testing\n\nRun `pytest plugins/pensive/tests/skills/test_architecture_review.py` to verify review logic.\n- [Architecture Principles Checklist](#architecture-principles-checklist)\n- [Coupling](#coupling)\n- [Cohesion](#cohesion)\n- [Layering](#layering)\n- [Evolution](#evolution)\n\n\n# Architecture Review Workflow\n\nArchitecture assessment against ADRs and design principles.\n\n## Quick Start\n\n```bash\n/architecture-review\n```\n\n## When To Use\n\n- Approving reimplementations.\n- Large-scale refactoring reviews.\n- System design changes.\n- New module/service introduction.\n- Dependency restructuring.\n\n## When NOT To Use\n\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n\n## Progressive Loading\n\nLoad modules based on review scope:\n\n- **`modules/adr-audit.md`** (~400 tokens): ADR verification and documentation.\n- **`modules/coupling-analysis.md`** (~450 tokens): Dependency analysis and boundary violations.\n- **`modules/principle-checks.md`** (~500 tokens): Code quality, security, and performance.\n- **`modules/fpf-methodology.md`** (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.\n\nLoad all modules for full reviews. For focused reviews, load only relevant modules.\n\n## Required TodoWrite Items\n\n1. `arch-review:context-established`: Repository, branch, motivation.\n2. `arch-review:adr-audit`: ADR verification and new ADR needs.\n3. `arch-review:interaction-mapping`: Module coupling analysis.\n4. `arch-review:invariant-check`: Invariant conflict detection and 3-option analysis.\n5. `arch-review:principle-checks`: LoD, security, performance.\n6. `arch-review:risks-actions`: Recommendation and follow-ups.\n\n## Workflow\n\n### Step 1: Establish Context (`arch-review:context-established`)\n\nConfirm repository and branch:\n```bash\npwd\ngit status -sb\n```\n\nDocument:\n- Feature/bug/epic motivating review.\n- Affected subsystems.\n- Architectural intent from README/docs.\n- Design trade-off assumptions.\n\n### Step 2: ADR Audit (`arch-review:adr-audit`)\n\n**Load: `modules/adr-audit.md`**\n\n- Locate ADRs in project.\n- Verify required sections.\n- Check status flow.\n- Confirm immutability compliance.\n- Flag need for new ADRs.\n\n### Step 3: Interaction Mapping (`arch-review:interaction-mapping`)\n\n**Load: `modules/coupling-analysis.md`**\n\n- Diagram before/after module interactions.\n- Verify composition boundaries.\n- Check data ownership clarity.\n- Validate dependency flow direction.\n- Identify coupling violations.\n\n### Step 3.5: Invariant Conflict Detection (`arch-review:invariant-check`)\n\nBefore checking principles, identify whether the changes\nconflict with existing design invariants. This is the\nhighest-judgment step in architecture review — models\nget this wrong more often than any other call.\n\n**Identify existing invariants:**\n\n1. Scan ADRs for recorded decisions still in \"accepted\"\n   status\n2. Check module boundaries (are imports crossing layers\n   that previously didn't?)\n3. Check data flow direction (does data now flow in a\n   new direction?)\n4. Check API contracts (are public interfaces changing\n   shape?)\n5. Check structural patterns (is a new pattern being\n   introduced alongside an existing one?)\n\n```bash\n# Detect boundary crossings in changed files\ngit diff --name-only | while read f; do\n  head -20 \"$f\" 2>/dev/null | rg \"^(import|from|use |require)\" || true\ndone\n```\n\n**When a conflict is detected:**\n\nDo NOT recommend a resolution. Present the three options\nand escalate to human judgment:\n\n| Option | When Right | When Wrong |\n|--------|------------|------------|\n| **Preserve invariant** (reject feature) | Invariant simplifies many things; feature is marginal | Feature is genuinely needed and invariant is stale |\n| **Layer on top** (add inelegantly) | Feature is needed; invariant still valuable; imperfection is OK | Layering creates a maintenance trap that will compound |\n| **Revise invariant** (change the design) | Genuine new learning invalidates the original reasoning | You're \"cleaning up\" a decision you don't fully understand |\n\n**Output format:**\n\n```markdown\n### Invariant Conflicts\n\n[I1] **[Invariant name]** — [what decision it represents]\n- **Conflict**: [what change clashes]\n- **Options**: Preserve / Layer / Revise\n- **Recommendation**: ESCALATE TO HUMAN\n- **Risk if wrong**: [what compounds]\n```\n\n**Why this matters:** Bad invariant decisions compound.\nAfter a few wrong calls the codebase becomes\nunsalvageable. This is a judgment problem, not a context\nproblem — the agent should surface it, not solve it.\n\n### Step 4: Principle Checks (`arch-review:principle-checks`)\n\n**Load: `modules/principle-checks.md`**\n\n- Law of Demeter.\n- Anti-slop patterns.\n- Security (input validation, least privilege).\n- Performance (N+1 queries, caching).\n\n### Step 5: Risks and Actions (`arch-review:risks-actions`)\n\nSummarize using `imbue:diff-analysis/modules/risk-assessment-framework`:\n- Current vs proposed architecture.\n- Business impact.\n- Technical debt implications.\n\nList follow-ups with owners and dates.\n\nProvide recommendation:\n- **Approve**: Architecture sound.\n- **Approve with actions**: Minor issues to address.\n- **Block**: Fundamental problems requiring redesign.\n\n## Architecture Principles Checklist\n\n### Coupling\n- [ ] Dependencies follow defined boundaries.\n- [ ] No circular dependencies.\n- [ ] Extension points used properly.\n- [ ] Abstractions don't leak.\n\n### Cohesion\n- [ ] Related functionality grouped.\n- [ ] Single responsibility per module.\n- [ ] Clear module purposes.\n\n### Layering\n- [ ] Layers have clear responsibilities.\n- [ ] Dependencies flow downward.\n- [ ] No layer bypassing.\n\n### Invariants\n- [ ] Existing design invariants identified.\n- [ ] Conflicts between changes and invariants surfaced.\n- [ ] Three-option analysis (preserve/layer/revise) presented.\n- [ ] Invariant changes escalated to human judgment.\n- [ ] No silent invariant revisions in the diff.\n\n### Evolution\n- [ ] Changes are reversible.\n- [ ] Migration paths are clear.\n- [ ] ADRs document decisions.\n\nFile v1.9.13:_meta.json\n\n{\n  \"ownerId\": \"kn7d107jg9jv602h9ytsegydq184a42s\",\n  \"slug\": \"nm-pensive-architecture-review\",\n  \"version\": \"1.9.13\",\n  \"publishedAt\": 1782577311074\n}\n\nFile v1.9.13:modules/adr-audit.md\n\n---\nname: adr-audit\ndescription: Architecture Decision Record audit patterns and verification workflow\n\nArchive v1.9.12: 7 files, 15244 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), skill-card.md (2121b), SKILL.md (7846b), _meta.json (150b)\n\nArchive v1.0.3: 7 files, 15350 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), skill-card.md (2334b), SKILL.md (7846b), _meta.json (149b)\n\nArchive v1.0.2: 7 files, 14455 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), skill-card.md (2542b), SKILL.md (5634b), _meta.json (149b)\n\nArchive v1.0.1: 6 files, 13148 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), SKILL.md (5634b), _meta.json (149b)\n\nArchive v1.0.0: 6 files, 13147 bytes\n\nFiles: modules/adr-audit.md (4055b), modules/coupling-analysis.md (8217b), modules/fpf-methodology.md (4168b), modules/principle-checks.md (7603b), SKILL.md (5634b), _meta.json (149b)","readmeExcerpt":"Skill: architecture-review Owner: athola Summary: Assesses architecture decisions, ADR compliance, and coupling Tags: latest:1.9.19 Version history: v1.9.19 | 2026-08-26T13:18:21.040Z | user Release v1.9.19 v1.9.17 | 2026-07-30T05:38:38.297Z | user Release v1.9.17 v1.9.16 | 2026-07-14T19:55:19.195Z | user Release v1.9.16 v1.9.14 | 2026-06-30T18:03:45.240Z | user Release v1.9.14 v1.9.13 | 2026-06-27T16:21:51.074Z | us","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"/architecture-review"},{"language":"bash","snippet":"pwd\ngit status -sb"},{"language":"bash","snippet":"# Detect boundary crossings in changed files\ngit diff --name-only | while read f; do\n  head -20 \"$f\" 2>/dev/null | rg \"^(import|from|use |require)\" || true\ndone"},{"language":"markdown","snippet":"### Invariant Conflicts\n\n[I1] **[Invariant name]** — [what decision it represents]\n- **Conflict**: [what change clashes]\n- **Options**: Preserve / Layer / Revise\n- **Recommendation**: ESCALATE TO HUMAN\n- **Risk if wrong**: [what compounds]"},{"language":"bash","snippet":"# Standard locations\nwiki/architecture/\ndocs/adr/\ndocs/decisions/\narchitecture/decisions/\n.adr/\n\n# Search pattern\nfind . -type f -name \"*ADR*\" -o -name \"*decision*\" | grep -E \"\\.(md|txt)$\""},{"language":"text","snippet":"Proposed → Reviewed → Accepted\n                    ↓\n              Superseded (when invalidated)"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: architecture-review\ndescription: Assesses architecture decisions, ADR compliance, and coupling\nversion: 1.9.8\ntriggers:\n  - architecture\n  - design\n  - adr\n  - coupling\n  - patterns\n  - principles\n  - evaluating design changes or validating structural decisions before merging\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/athola/claude-night-market/tree/master/plugins/pensive\", \"emoji\": \"\\ud83c\\udfd7\\ufe0f\", \"requires\": {\"config\": [\"night-market.pensive:shared\", \"night-market.imbue:proof-of-work\", \"night-market.imbue:diff-analysis/modules/risk-assessment-framework\"]}}}\nsource: claude-night-market\nsource_plugin: pensive\n---\n\n> **Night Market Skill** — ported from [claude-night-market/pensive](https://github.com/athola/claude-night-market/tree/master/plugins/pensive). For the full experience with agents, hooks, and commands, install the Claude Code plugin.\n\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [When to Use](#when-to-use)\n- [Progressive Loading](#progressive-loading)\n- [Required TodoWrite Items](#required-todowrite-items)\n- [Workflow](#workflow)\n- [Step 1: Establish Context (`arch-review:context-established`)](#step-1:-establish-context-(arch-review:context-established))\n- [Step 2: ADR Audit (`arch-review:adr-audit`)](#step-2:-adr-audit-(arch-review:adr-audit))\n- [Step 3: Interaction Mapping (`arch-review:interaction-mapping`)](#step-3:-interaction-mapping-(arch-review:interaction-mapping))\n- [Step 4: Principle Checks (`arch-review:principle-checks`)](#step-4:-principle-checks-(arch-review:principle-checks))\n- [Step 5: Risks and Actions (`arch-review:risks-actions`)](#step-5:-risks-and-actions-(arch-review:risks-actions))\n- [Testing](#testing)\n\n## Testing\n\nRun `pytest plugins/pensive/tests/skills/test_architecture_review.py` to verify review logic.\n- [Architecture Principles Checklist](#architecture-principles-checklist)\n- [Coupling](#coupling)\n- [Cohesion](#cohesion)\n- [Layering](#layering)\n- [Evolution](#evolution)\n\n\n# Architecture Review Workflow\n\nArchitecture assessment against ADRs and design principles.\n\n## Quick Start\n\n```bash\n/architecture-review\n```\n\n## When To Use\n\n- Approving reimplementations.\n- Large-scale refactoring reviews.\n- System design changes.\n- New module/service introduction.\n- Dependency restructuring.\n\n## When NOT To Use\n\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n- Selecting architecture paradigms - use archetypes\n  skills\n- API surface review - use api-review\n\n## Progressive Loading\n\nLoad modules based on review scope:\n\n- **`modules/adr-audit.md`** (~400 tokens): ADR verification and documentation.\n- **`modules/coupling-analysis.md`** (~450 tokens): Dependency analysis and boundary violations.\n- **`modules/principle-checks.md`** (~500 tokens): Code quality, security, and performance.\n- **`modules/fpf-methodology.md`** (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.\n\nLoad all modules for "},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7d107jg9jv602h9ytsegydq184a42s\",\n  \"slug\": \"nm-pensive-architecture-review\",\n  \"version\": \"1.9.19\",\n  \"publishedAt\": 1787750301040\n}"},{"path":"modules/adr-audit.md","content":"---\nname: adr-audit\ndescription: Architecture Decision Record audit patterns and verification workflows\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [adr, documentation, governance, decisions]\ncomplexity: intermediate\nestimated_tokens: 400\n---\n\n# ADR Audit Module\n\ndetailed ADR discovery, validation, and governance patterns.\n\n## ADR Location Patterns\n\nCommon ADR locations by project type:\n\n```bash\n# Standard locations\nwiki/architecture/\ndocs/adr/\ndocs/decisions/\narchitecture/decisions/\n.adr/\n\n# Search pattern\nfind . -type f -name \"*ADR*\" -o -name \"*decision*\" | grep -E \"\\.(md|txt)$\"\n```\n\n## Required ADR Sections\n\nEvery ADR must include:\n\n### 1. Title\nClear, specific decision statement:\n- \"Use PostgreSQL for primary datastore\"\n- \"Adopt hexagonal architecture pattern\"\n- \"Implement JWT-based authentication\"\n\n### 2. Status\nMust follow strict progression:\n```\nProposed → Reviewed → Accepted\n                    ↓\n              Superseded (when invalidated)\n```\n\n**Rules:**\n- Status changes are append-only\n- Date each status transition\n- Never delete/modify accepted ADRs\n- Use \"Superseded by ADR-XXX\" to replace\n\n### 3. Context\nDocument the forces at play:\n- Business requirements\n- Technical constraints\n- Team capabilities\n- Timeline pressures\n- Existing architecture\n\n### 4. Decision\nThe \"we will...\" statement:\n- Clear action chosen\n- Implementation approach\n- Key design choices\n\n### 5. Alternatives Considered\nFor each alternative:\n- Description\n- Pros/cons\n- Why rejected\n\nMinimum 2 alternatives required.\n\n### 6. Consequences\n\n**Positive:**\n- Benefits gained\n- Problems solved\n- Capabilities enabled\n\n**Negative:**\n- Trade-offs accepted\n- Technical debt incurred\n- Complexity added\n\n**Neutral:**\n- Changes required\n- Migration steps\n- Training needs\n\n### 7. Metadata\n```yaml\nDate: YYYY-MM-DD\nAuthor: [name]\nStatus: [status]\nSupersedes: [ADR-XXX] (if applicable)\nSuperseded-by: [ADR-XXX] (if applicable)\n```\n\n## Status Flow Verification\n\n### Valid Transitions\n- Proposed → Reviewed\n- Reviewed → Accepted\n- Reviewed → Rejected\n- Accepted → Superseded (via new ADR only)\n\n### Invalid Transitions\n- Proposed -> Accepted (skip review)\n- Accepted -> Rejected (use Superseded)\n- Superseded -> Accepted (immutable)\n\n## Immutability Rules\n\n**Once Accepted:**\n1. **Never modify** decision content\n2. **Never change** consequences\n3. **Never delete** the ADR\n4. **Only append** status changes\n\n**To Replace:**\n1. Create new ADR with superseding decision\n2. Add \"Supersedes: ADR-XXX\" to new ADR\n3. Add \"Superseded-by: ADR-YYY\" to old ADR\n4. Update old ADR status to \"Superseded\"\n\n## Audit Workflow\n\n### 1. Locate All ADRs\n```bash\n# Find ADR directory\nls -la docs/adr/ wiki/architecture/ 2>/dev/null\n\n# Count ADRs\nfind . -path \"*/adr/*.md\" -o -path \"*/decisions/*.md\" | wc -l\n```\n\n### 2. Verify Structure\nFor each ADR:\n- [ ] Has all required sections\n- [ ] Status follows valid flow\n- [ ] Dates are present\n- [ ] Alternatives documented (≥2)\n- [ ] Consequences specified\n\n"},{"path":"modules/coupling-analysis.md","content":"---\nname: coupling-analysis\ndescription: Interaction mapping, composition boundaries, and dependency flow analysis\nparent_skill: pensive:architecture-review\ncategory: architecture\ntags: [coupling, dependencies, composition, boundaries, modularity]\ncomplexity: advanced\nestimated_tokens: 450\n---\n\n# Coupling Analysis Module\n\nSystematic analysis of module interactions, boundaries, and dependency flows.\n\n## Interaction Mapping Patterns\n\n### Visual Representation\n\nCreate before/after diagrams:\n\n```\nBefore:\n┌─────────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│Module B │────▶│ Database │\n└─────────┘     └─────────┘     └──────────┘\n\nAfter:\n┌─────────┐     ┌───────┐     ┌─────────┐     ┌──────────┐\n│Module A │────▶│ Cache │────▶│Module B │────▶│ Database │\n└─────────┘     └───────┘     └─────────┘     └──────────┘\n```\n\n### Dependency Graph Tools\n\n```bash\n# Python: Generate import graph\npydeps --max-bacon=2 --cluster src/\n\n# TypeScript: Analyze module dependencies\nmadge --circular --extensions ts src/\n\n# Generic: Find direct dependencies\ngrep -r \"import\\|require\\|from\" src/ | cut -d: -f1 | sort | uniq -c\n```\n\n## Composition Boundaries\n\n### Boundary Definition\n\nClear boundaries have:\n1. **Explicit interfaces** - Published contracts\n2. **Data ownership** - Single source of truth\n3. **Encapsulation** - Hidden implementation\n4. **Stability** - Minimal breaking changes\n\n### Boundary Types\n\n**Module Boundaries:**\n```\n┌──────────────────────────┐\n│   Public API             │\n├──────────────────────────┤\n│   Internal Logic         │\n│   (implementation)       │\n└──────────────────────────┘\n```\n\n**Layer Boundaries:**\n```\n┌──────────────────────────┐\n│   Presentation Layer     │ ← HTTP/UI\n├──────────────────────────┤\n│   Application Layer      │ ← Business Logic\n├──────────────────────────┤\n│   Domain Layer           │ ← Core Models\n├──────────────────────────┤\n│   Infrastructure Layer   │ ← Database/External\n└──────────────────────────┘\n```\n\n**Service Boundaries:**\n```\nService A          Service B\n┌────────┐        ┌────────┐\n│  API   │◀──────▶│  API   │\n├────────┤        ├────────┤\n│  DB A  │        │  DB B  │\n└────────┘        └────────┘\n```\n\n### Boundary Violations\n\n**Ad-hoc Reach-ins:**\n```python\n# Bad: Reaching through module boundary\nuser.profile.settings.theme.get_color()\n\n# Good: Ask for what you need\nuser.get_theme_color()\n```\n\n**Layering Violations:**\n```python\n# Bad: Domain layer accessing infrastructure\nclass Order:\n    def save(self):\n        db.execute(\"INSERT INTO orders...\")\n\n# Good: Infrastructure handles persistence\nclass OrderRepository:\n    def save(self, order: Order):\n        db.execute(\"INSERT INTO orders...\")\n```\n\n## Data Ownership Analysis\n\n### Single Owner Principle\n\nEach data entity has exactly one authoritative owner:\n\n```\nUser Data:\n├── Auth Service (owner: credentials)\n├── Profile Service (owner: profile data)\n└── Analytics Service (consumer: read-only)\n```\n\n### Ownership Violations\n\n**Multiple Writers:**\n```python\n# Bad: Two "},{"path":"modules/fpf-methodology.md","content":"# FPF Architecture Review Methodology\n\nConduct architecture reviews using the FPF (Functional, Practical, Foundation) methodology, evaluating codebases through three complementary perspectives.\n\n## Philosophy\n\nArchitecture reviews should be systematic and multi-dimensional. FPF provides three lenses:\n- **Functional**: What the system does (capabilities, behaviors)\n- **Practical**: How well it works (performance, usability)\n- **Foundation**: What it's built on (principles, patterns)\n\n## Quick Start\n\n```bash\n# Full FPF review\n/architecture-review --methodology fpf\n\n# Specific perspective\n/architecture-review --perspective functional\n/architecture-review --perspective practical\n/architecture-review --perspective foundation\n```\n\n## The Three Perspectives\n\n### 1. Functional Perspective\n\n**Question:** What does this system do?\n\n**Evaluates:**\n- Feature completeness\n- Capability coverage\n- Behavior correctness\n- Integration points\n\n**Outputs:**\n- Feature inventory\n- Capability gaps\n- Behavior anomalies\n\n### 2. Practical Perspective\n\n**Question:** How well does this system work?\n\n**Evaluates:**\n- Performance characteristics\n- Usability patterns\n- Operational concerns\n- Scalability considerations\n\n**Outputs:**\n- Performance assessment\n- Usability issues\n- Operational recommendations\n\n### 3. Foundation Perspective\n\n**Question:** What is this system built on?\n\n**Evaluates:**\n- Architectural patterns\n- Design principles\n- Code quality\n- Technical debt\n\n**Outputs:**\n- Pattern analysis\n- Principle adherence\n- Debt inventory\n\n## FPF Workflow\n\n### Phase 1: Discovery\n1. Scan codebase structure - Identify components, modules, layers\n2. Map dependencies - Internal and external relationships\n3. Identify entry points - Public APIs, commands, interfaces\n\n### Phase 2: Functional Analysis\n1. Inventory features - What capabilities exist\n2. Trace behaviors - How features work end-to-end\n3. Identify gaps - Missing or incomplete functionality\n\n### Phase 3: Practical Analysis\n1. Assess performance - Latency, throughput, resource usage\n2. Evaluate usability - Developer experience, API design\n3. Check operations - Logging, monitoring, error handling\n\n### Phase 4: Foundation Analysis\n1. Pattern recognition - What patterns are used\n2. Principle check - SOLID, DRY, KISS adherence\n3. Debt assessment - Technical debt inventory\n\n### Phase 5: Synthesis\n1. Cross-reference findings - Connect issues across perspectives\n2. Prioritize recommendations - Based on impact and effort\n3. Generate report - Structured findings and actions\n\n## FPF Report Template\n\n```markdown\n# FPF Architecture Review: [Project/Component]\n\n**Date:** [DATE]\n**Scope:** [what was reviewed]\n\n## Executive Summary\n[2-3 sentence overview of findings]\n\n## Functional Perspective\n### Features Inventory\n| Feature | Status | Notes |\n|---------|--------|-------|\n| [Feature 1] | Complete | - |\n\n### Capability Gaps\n1. [Gap 1] - [Impact]\n\n## Practical Perspective\n### Performance Assessment\n| Metric | Current | Target | Status |\n|"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Assesses architecture decisions, ADR compliance, and coupling Skill: architecture-review Owner: athola Summary: Assesses architecture decisions, ADR compliance, and coupling Tags: latest:1.9.19 Version history: v1.9.19 | 2026-08-26T13:18:21.040Z | user Release v1.9.19 v1.9.17 | 2026-07-30T05:38:38.297Z | user Release v1.9.17 v1.9.16 | 2026-07-14T19:55:19.195Z | user Release v1.9.16 v1.9.14 | 2026-06-30T18:03:45.240Z | user Release v1.9.14 v1.9.13 | 2026-06-27T16:21:51.074Z | us","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1163,"uniquenessScore":53,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T04:36:31.067Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T04:36:31.067Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:59:43.780Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}