Nm Pensive Architecture Review

Assess architecture decisions, ADR compliance, coupling analysis, and design principles

Security Scan

The skill is an instruction-only architecture-review helper whose requested configuration and runtime actions are consistent with its stated purpose (scanning a codebase, running searches, and producing ADR/coupling/principle checks).

Purpose & Capability

The name/description match the SKILL.md and included modules (ADR audit, coupling analysis, principle checks, FPF methodology). The declared required config paths (night-market.pensive:shared, night-market.imbue:proof-of-work, night-market.imbue:diff-analysis/modules/risk-assessment-framework) are internal configuration references consistent with producing structured reviews and risk assessments. No unrelated credentials, binaries, or system-wide privileges are requested.

Instruction Scope

The instructions expect the agent to inspect repository files and run file-search commands (find, grep), static-analysis helpers (pydeps, madge), and tests (pytest plugin). That's normal for an architecture review, but it does mean the skill will read and analyze local code and docs. The SKILL.md does not instruct reading unrelated system paths or exfiltrating data to external endpoints.

Install Mechanism

No install spec or bundled code is present (instruction-only). That minimizes risk because nothing is downloaded or written to disk by the skill itself. The skill does reference external tools (pydeps, madge, pytest) but does not attempt to install them.

Credentials

The skill requests no environment variables or credentials. It does declare three required config paths in the Night Market config namespace; these appear to be internal configuration hooks for the review workflow and are proportionate to a review/reporting skill. If you do not use Night Market config namespaces, these config requirements are inert.

Persistence & Privilege

always is false and the skill is user-invocable; autonomous invocation is allowed by platform defaults but this skill does not request persistent privileges, nor does it attempt to modify other skills or system-wide settings.

Assessment

This skill is coherent with its stated purpose: it reads and analyzes the codebase (find/grep, dependency graph tools, test invocation) and does not request secrets. Before installing or invoking: 1) only run it on repositories you trust, since it will scan files and run test/analysis commands; 2) ensure required analysis tools (pydeps, madge, pytest) are present if you need full functionality; 3) review any Night Market config entries it requests if you use that platform (they are internal config references, not API keys); 4) if you want to restrict autonomous runs, keep it user-invocable only and monitor what reviews are performed.

Night Market Skill — ported from claude-night-market/pensive. For the full experience with agents, hooks, and commands, install the Claude Code plugin.

Table of Contents

• Quick Start
• When to Use
• Progressive Loading
• Required TodoWrite Items
• Workflow
• Step 1: Establish Context (arch-review:context-established)
• Step 2: ADR Audit (arch-review:adr-audit)
• Step 3: Interaction Mapping (arch-review:interaction-mapping)
• Step 4: Principle Checks (arch-review:principle-checks)
• Step 5: Risks and Actions (arch-review:risks-actions)
• Testing

Testing

Run pytest plugins/pensive/tests/skills/test_architecture_review.py to verify review logic.

• Architecture Principles Checklist
• Coupling
• Cohesion
• Layering
• Evolution

Architecture Review Workflow

Architecture assessment against ADRs and design principles.

Quick Start

/architecture-review

When To Use

• Approving reimplementations.
• Large-scale refactoring reviews.
• System design changes.
• New module/service introduction.
• Dependency restructuring.

When NOT To Use

• Selecting architecture paradigms - use archetypes skills
• API surface review - use api-review
• Selecting architecture paradigms - use archetypes skills
• API surface review - use api-review

Progressive Loading

Load modules based on review scope:

• modules/adr-audit.md (~400 tokens): ADR verification and documentation.
• modules/coupling-analysis.md (~450 tokens): Dependency analysis and boundary violations.
• modules/principle-checks.md (~500 tokens): Code quality, security, and performance.
• modules/fpf-methodology.md (~800 tokens): FPF (Functional, Practical, Foundation) multi-perspective review methodology.

Load all modules for full reviews. For focused reviews, load only relevant modules.

Required TodoWrite Items

1. arch-review:context-established: Repository, branch, motivation.
2. arch-review:adr-audit: ADR verification and new ADR needs.
3. arch-review:interaction-mapping: Module coupling analysis.
4. arch-review:principle-checks: LoD, security, performance.
5. arch-review:risks-actions: Recommendation and follow-ups.

Workflow

Step 1: Establish Context (arch-review:context-established)

Confirm repository and branch:

pwd
git status -sb

Document:

• Feature/bug/epic motivating review.
• Affected subsystems.
• Architectural intent from README/docs.
• Design trade-off assumptions.

Step 2: ADR Audit (arch-review:adr-audit)

Load: modules/adr-audit.md

• Locate ADRs in project.
• Verify required sections.
• Check status flow.
• Confirm immutability compliance.
• Flag need for new ADRs.

Step 3: Interaction Mapping (arch-review:interaction-mapping)

Load: modules/coupling-analysis.md

• Diagram before/after module interactions.
• Verify composition boundaries.
• Check data ownership clarity.
• Validate dependency flow direction.
• Identify coupling violations.

Step 4: Principle Checks (arch-review:principle-checks)

Load: modules/principle-checks.md

• Law of Demeter.
• Anti-slop patterns.
• Security (input validation, least privilege).
• Performance (N+1 queries, caching).

Step 5: Risks and Actions (arch-review:risks-actions)

Summarize using imbue:diff-analysis/modules/risk-assessment-framework:

• Current vs proposed architecture.
• Business impact.
• Technical debt implications.

List follow-ups with owners and dates.

Provide recommendation:

• Approve: Architecture sound.
• Approve with actions: Minor issues to address.
• Block: Fundamental problems requiring redesign.

Architecture Principles Checklist

Coupling

• Dependencies follow defined boundaries.
• No circular dependencies.
• Extension points used properly.
• Abstractions don't leak.

Cohesion

• Related functionality grouped.
• Single responsibility per module.
• Clear module purposes.

Layering

• Layers have clear responsibilities.
• Dependencies flow downward.
• No layer bypassing.

Evolution

• Changes are reversible.
• Migration paths are clear.
• ADRs document decisions.

Troubleshooting

Common Issues

Command not found Ensure all dependencies are installed and in PATH

Permission errors Check file permissions and run with appropriate privileges

Unexpected behavior Enable verbose logging with --verbose flag