name	Dev10x:project-audit
description	Comprehensive project-level architecture audit and quality review. Catalogs design patterns from Fowler PoEAA, Refactoring Guru, and Software Archetypes, then stress-tests the codebase against those catalogs. Collects JTBD from closed PRs, maps against test coverage, identifies anemic models, Tell Don't Ask violations, missing Protocols, and scattered validation. Produces milestoned issue backlog with blocking chains and ADR proposals. TRIGGER when: user asks to audit, review architecture, find design gaps, stress-test patterns, catalog JTBD, or run a comprehensive quality review of the project. DO NOT TRIGGER when: reviewing a single PR (use Dev10x:gh-pr-review), scoping a single ticket (use Dev10x:ticket-scope), or doing a session-level skill audit (use Dev10x:skill-audit).
user-invocable	true
invocation-name	Dev10x:project-audit
allowed-tools	Agent WebFetch Grep Glob Read Bash(gh issue create:*) Bash(gh issue edit:*) Bash(gh issue list:*) Bash(gh issue view:*) Bash(gh api repos/:*) Bash(gh pr list:*) Bash(gh label create:*) Bash(gh label list:*) Bash(git log:*) Bash(git diff:*) Bash(git develop-log:*) Bash(git develop-diff:*) Bash(/tmp/claude/bin/mktmp.sh:*) Write(/tmp/claude/**) AskUserQuestion TaskCreate TaskUpdate Skill(Dev10x:project-scope) Skill(Dev10x:ticket-create) Skill(Dev10x:adr) mcp__plugin_Dev10x_cli__mktmp mcp__plugin_Dev10x_cli__detect_tracker

Dev10x:project-audit — Comprehensive Project Architecture Audit

Overview

A multi-phase, agent-driven audit that evaluates an entire project against established design pattern catalogs, extracts delivered value (JTBD) from PR history, identifies architectural gaps, and produces a prioritized backlog of improvements.

Think of it as a "tech due diligence" you'd run before a major release, an acquisition, or onboarding a new team.

Use when:

• Starting work on a new-to-you codebase
• Preparing for a major release and want to find gaps
• Running periodic architecture health checks
• User says "audit the project", "find design gaps", "stress-test the architecture"

Do NOT use for:

• Single PR review -> Dev10x:gh-pr-review
• Single ticket scoping -> Dev10x:ticket-scope
• Session-level skill audit -> Dev10x:skill-audit

Orchestration

This skill follows references/task-orchestration.md patterns (Tier: Complex).

Auto-advance: Complete each phase and immediately start the next. Never pause between phases to ask "should I continue?".

REQUIRED: Create tasks before ANY work. Execute these TaskCreate calls at startup:

1. TaskCreate(subject="Detect project context", activeForm="Detecting project context")
2. TaskCreate(subject="Select audit phases", activeForm="Selecting audit phases")
3. TaskCreate(subject="Execute audit phases", activeForm="Executing audit")
4. TaskCreate(subject="Synthesize findings", activeForm="Synthesizing findings")
5. TaskCreate(subject="Create backlog structure", activeForm="Creating backlog")

Set sequential dependencies.

Phase 1: Detect Project Context

1.1 Identify Project Shape

Automatically detect:

• Language/framework — scan for pyproject.toml, package.json, Cargo.toml, go.mod
• Architecture style — monorepo vs polyrepo, monolith vs microservices vs modular monolith
• Bounded contexts / modules — list top-level source directories
• Test infrastructure — pytest, vitest, playwright, jest, etc.
• Issue tracker — call mcp__plugin_Dev10x_cli__detect_tracker
• Existing ADRs — scan docs/adr/ or equivalent
• Existing pattern docs — scan .claude/references/rules/, CLAUDE.md

1.2 Collect PR History

Fetch closed/merged PRs:

gh pr list --state closed --limit 200 --json number,title,body,mergedAt,labels

Extract JTBD (Job Stories) from PR bodies. Look for:

• Explicit **When** ... **I want to** ... **so I can** patterns
• Infer JTBD from title + body if not explicit
• Separate feature PRs (gitmoji: sparkles, bug, recycle) from bot/maintenance PRs (robot)

1.3 Collect Existing Test Coverage

• List all test files and feature files
• Map test files to source modules (1:1 pathing convention)
• Identify modules with zero test files

Phase 2: Select Audit Phases

REQUIRED: Call AskUserQuestion to let the user select which audit phases to run. Present as multi-select.

Available Audit Phases

Phase	Name	Description	Time
A	Pattern Catalog	Map Fowler PoEAA, Refactoring Guru, and Software Archetypes to codebase	Medium
B	Domain Model Health	Classify models as Active Record / Anemic / Rich, find Tell Don't Ask violations	Medium
C	Value Object Discovery	Identify primitives that should be Value Objects with behavior	Small
D	Archetype Stress Test	Verify Software Archetypes structural alignment	Medium
E	Concurrency Audit	Verify locks, transactions, and race condition protection	Medium
F	Behavioral Pattern Fit	Evaluate Strategy, CoR, Template Method opportunities	Small
G	JTBD Coverage Matrix	Map delivered JTBD against e2e and unit test coverage	Medium
H	Cross-Cutting Consistency	Find inconsistent patterns across modules	Small

Default selection: all phases. User can deselect irrelevant phases.

Phase 3: Execute Audit Phases

Dispatch Strategy

Launch parallel agents for independent phases. Phases A-F can all run concurrently. Phase G depends on Phase 1 PR collection.

Each agent receives:

1. Project context from Phase 1
2. Phase-specific audit checklist
3. Structured output format instructions

Agent Output Format

Every agent must report findings as:

### Finding: {short title}
- **Location:** {file_path}:{line_range}
- **Pattern:** {which pattern from which catalog}
- **Current:** {what the code does now}
- **Issue:** {what's wrong or missing}
- **Recommendation:** {specific change}
- **Impact:** HIGH / MEDIUM / LOW
- **Effort:** S / M / L

Phase A: Pattern Catalog

Fetch pattern catalogs from three authoritative sources:

1. Fowler PoEAA — https://martinfowler.com/eaaCatalog/ Focus: Repository, Unit of Work, Service Layer, DTO, Value Object, Gateway, Identity Map, Optimistic/Pessimistic Lock, Layer Supertype, Separated Interface, Active Record vs Domain Model distinction

2. Refactoring Guru — https://refactoring.guru/design-patterns/catalog Focus: Strategy, State, Chain of Responsibility, Template Method, Factory Method, Observer, Mediator, Command, Decorator, Adapter

3. Software Archetypes — https://www.softwarearchetypes.com/ Focus: Party, Availability, Waitlist, GAP, Configurator, Rule Engine

For each pattern, classify as:

• Adopted — implemented and documented (cite ADR or file)
• Implicit — used but not formally documented
• Applicable — fits a current problem but isn't used
• Not Applicable — doesn't fit the domain

Adapt focus to the detected framework:

• Django/Rails -> Active Record, Repository, Unit of Work, Service Layer
• Node/Express -> Middleware, Strategy, Chain of Responsibility
• Go -> Interface segregation, Repository, Factory

Phase B: Domain Model Health

For each model/entity class:

1. Count behavior methods (excluding __str__, __repr__, Meta):

   • 0 methods -> Anemic (anti-pattern if model has state transitions)
   • 1-3 methods -> Lean Active Record (acceptable for simple CRUD)
   • 4+ methods -> Rich Domain Model (ideal for complex domains)

2. Find Tell Don't Ask violations — search services and handlers for:

   • if model.field == VALUE followed by model.field = NEW_VALUE
   • for item in model.json_field: (reaching into aggregate internals)
   • model.field < timezone.now() (expiry checks that should be methods)

3. Find module-level orchestration — functions that take a model, read its attributes, compute, then write back. These should be methods on the model class.

4. Produce classification table for all models with verdicts.

Phase C: Value Object Discovery

Search for primitive types used in 3+ places with the same validation:

• str with format validation (emails, codes, PINs)
• int with range constraints (slot indices, durations)
• datetime with expiry checks (tokens, invitations)
• Field groups that always travel together (schedule = date + time + count + duration)

For each candidate: count duplication sites, propose VO interface, estimate lines of scattered validation eliminated.

Phase D: Archetype Stress Test

For each archetype the project maps to:

1. List canonical structural elements the archetype prescribes
2. List what the codebase actually has
3. Score alignment (1-5)
4. Identify missing entities the archetype expects
5. Identify structural deviations
6. Recommend fixes ranked by impact

Phase E: Concurrency Audit

For every mutating operation:

1. Check for transaction wrapping (@transaction.atomic or equivalent)
2. Check for row locks on check-then-act patterns (SELECT FOR UPDATE)
3. Check for unique constraint backstops
4. Check that IntegrityError is caught and mapped to domain exceptions
5. Classify: SAFE / RACE CONDITION / UNKNOWN

Cross-reference with Fowler's Offline Concurrency patterns.

Phase F: Behavioral Pattern Fit

Evaluate opportunities for:

• Strategy — swappable algorithms (delivery, notification channels)
• Chain of Responsibility — validation rule chains
• Template Method — handler/service base classes
• State — vs inline state machine (count state-dependent behaviors)
• Factory Method — service instantiation consistency
• Mediator — cross-module communication

For each: benefit vs cost. Verdict: adopt / skip / defer.

Phase G: JTBD Coverage Matrix

Using JTBD from Phase 1:

1. Map each feature JTBD to test files (e2e + unit)
2. Classify: FULL / PARTIAL (happy path only) / NONE
3. Identify orphaned tests (no matching JTBD)
4. Identify inconsistencies between test descriptions and JTBD

Phase H: Cross-Cutting Consistency

Search for inconsistent patterns across modules:

• Handler registration (function vs class-based)
• Service instantiation (factory vs container vs direct)
• Error handling (custom exceptions vs ValueError vs bare)
• Method naming (execute vs call vs named methods)
• Repository Protocol signatures
• Import patterns (inline vs top-level)

Count occurrences of each variant, recommend the dominant pattern.

Phase 4: Synthesize Findings

4.1 Merge Agent Reports

Collect all agent findings into a single document.

4.2 Prioritize

Score each finding on two axes:

	HIGH Impact	MEDIUM Impact	LOW Impact
S Effort	P0	P1	P2
M Effort	P1	P2	P3
L Effort	P2	P3	Backlog

4.3 Group into Milestones

Natural milestone grouping:

1. Foundation — shared kernel extractions, base classes, Protocols
2. Per-module enrichment — one milestone per BC or major module
3. Test coverage — new tests for identified gaps
4. Documentation — ADR proposals, pattern catalog memo

4.4 Write Memo

Write findings to docs/memos/YYYY-MM/NNNN-YYYY-MM-DD-project-audit.md:

• Executive summary (1 paragraph)
• Findings by phase (tables, not prose)
• Priority matrix
• Recommended milestone structure
• Pattern catalog (adopted / implicit / applicable)

4.5 Propose ADRs

For HIGH impact findings that change architectural direction:

• Draft ADR proposals citing pattern source (Fowler page, refactoring.guru URL, archetype)
• Use project's existing ADR template
• Status: Proposed

Phase 5: Create Backlog Structure

REQUIRED: Call AskUserQuestion to confirm milestone and ticket structure before creating.

5.1 Detect Tracker

Use mcp__plugin_Dev10x_cli__detect_tracker or ask user.

5.2 Batch-Create

Use sidecar metadata pattern from Dev10x:project-scope:

1. Write .md body files and .vars metadata files
2. Create all issues in a single loop
3. Update blocking references with real issue numbers

5.3 Report

Present final summary:

• Milestone list with issue counts
• Blocking chain visualization (ASCII)
• Links to all created entities
• Recommended session-per-milestone execution order

Key Detection Heuristics

Tell Don't Ask (core heuristic)

# ANTI-PATTERN (Ask):
if model.status == Status.PENDING:    # asking
    model.status = Status.APPROVED    # then telling
    model.approved_by = user_id       # then telling more

# CORRECT (Tell):
model.approve(approved_by=user_id)    # tell the model what to do

Grep patterns to find violations:

• if {var}.status == or if {var}.status != in service files
• {var}.status = outside model methods
• {var}.field < timezone.now() in service files (expiry should be a method)

Module-Level Orchestration Detection

# ANTI-PATTERN (external orchestration):
def process_invitation(invitation, user_id, repo):
    for role in invitation.intended_roles:     # reaching in
        repo.save(MembershipRole(...))         # doing work outside
    invitation.status = "ACCEPTED"             # mutating externally

# CORRECT (encapsulated):
invitation.realize_for_user(user_id=user_id, repo=repo)

Anemic Model Detection

Count methods per model class (excluding str, repr, Meta, save, delete):

• 0 behavioral methods + has status/state field = ANEMIC
• 0 behavioral methods + no state field = DATA RECORD (acceptable)

Concurrency Checklist

For each mutating operation, verify ALL of:

• Wrapped in @transaction.atomic
• Check-then-act uses SELECT FOR UPDATE
• DB unique constraint exists as backstop
• IntegrityError caught and mapped to domain exception
• No bare if not exists: create without lock

Error Handling

Scenario	Behavior
Agent returns empty findings	Log "no findings" for that phase, continue
WebFetch fails for pattern catalog	Use hardcoded pattern list as fallback
Too many PRs (>500)	Sample: first 100 + last 100 + random 50
No test files found	Skip Phase G, note in findings
No ADR directory	Skip ADR proposals, note in findings

Integration with Other Skills

Trigger	Skill	Direction
Backlog needs milestones + issues	Dev10x:project-scope	Delegates to (Phase 5)
Finding needs an ADR	Dev10x:adr	Proposes via (Phase 4.5)
User scopes a specific finding	Dev10x:ticket-scope	User invokes manually
User starts working a ticket	Dev10x:work-on	User invokes manually

Arguments

/Dev10x:project-audit                    # full audit, all phases
/Dev10x:project-audit --phases B,C,E     # selected phases only
/Dev10x:project-audit --skip-backlog     # findings only, no tickets
/Dev10x:project-audit --memo-only        # write memo, no tickets or ADRs