Review Brief Alignment

Establish the scope, goals, and alignment matrix for a brownfield architecture review. This is the first step in the brownfield pipeline — it takes review goals and codebase context and produces a structured review brief plus alignment matrix mapping goals to codebase areas.

When to Use This Skill

• Starting a new architecture review of an existing codebase
• Need to scope what areas of the codebase to analyze
• Stakeholders need alignment on review priorities
• Transitioning a legacy system and need to understand what to evaluate
• Creating a foundation for downstream brownfield analysis (discovery, gap analysis, migration)

Pipeline Position

[Review Goals + Codebase] --> **REVIEW BRIEF ALIGNMENT** --> [REVIEW_BRIEF.md + ALIGNMENT_MATRIX.md] --> Codebase Discovery --> ...

Input: User-provided review goals, codebase path Output: REVIEW_BRIEF.md and ALIGNMENT_MATRIX.md written to artifacts directory

Artifact Template

Both output artifacts follow the standard artifact template:

# [ARTIFACT TITLE]
## Summary
## Inputs
## Outputs
## Assumptions
## Open Questions
## Main Content
## Acceptance Criteria

Process

Step 1: Gather Review Context

Collect all inputs needed to scope the review.

1. Read user-provided review goals from --goals flag or interactive prompt
2. Scan codebase root for project identity:
   • Use Glob to enumerate top-level directory structure
   • Identify build system manifests: package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Makefile, CMakeLists.txt, *.csproj, *.sln
   • Read the primary manifest to extract project name, version, dependencies
   • Check for .git/ to confirm version control presence
   • Read README.md if present for project description context
3. Identify language and framework indicators:
   • Source file extensions (.py, .ts, .go, .rs, .java, .swift, etc.)
   • Framework-specific directories (src/app/, pages/, controllers/, handlers/, etc.)
   • Configuration files (.eslintrc, tsconfig.json, setup.cfg, Dockerfile, etc.)
4. Record codebase metadata:
   • Approximate file count by extension using Glob
   • Top-level directory names and apparent purpose
   • Presence of test directories (tests/, __tests__/, spec/, test/)
   • Presence of CI/CD configuration (.github/workflows/, .gitlab-ci.yml, Jenkinsfile)

Evidence requirement: Every observation about the codebase MUST cite a specific file.

> Project uses TypeScript with React [package.json:5]
> Test suite uses Jest [package.json:22]

Step 2: Define Review Scope

Explicitly state what is included and excluded from the review.

1. In-scope areas: List directories, modules, layers, and concerns that will be analyzed
2. Out-of-scope areas: List directories, modules, or concerns explicitly excluded (e.g., third-party vendored code, generated files, documentation-only directories)
3. Depth constraints: Define how deep the analysis goes:
   • Surface: Directory structure, manifest files, top-level architecture only
   • Standard: Entry points, routing, data models, key abstractions, dependency graph
   • Deep: Line-level analysis of critical paths, performance hotspots, security surfaces
4. Time constraints: If applicable, note time budget for the review
5. Boundary justification: For each in/out scope decision, provide rationale citing codebase evidence

Step 3: Establish Goals

Create a structured goal inventory with deterministic identifiers.

1. Extract goals from user input (explicit goals) and codebase context (implied goals)
2. Assign GOAL-NNNN IDs: Sort all goals alphabetically by goal title, then assign sequential four-digit numbers starting at GOAL-0001
3. Assign priorities:
   • P0 (Critical): Blocking issues that prevent system operation or pose immediate risk
   • P1 (Significant): Important issues that degrade quality, maintainability, or velocity
   • P2 (Minor): Nice-to-have improvements, cosmetic or long-term concerns
4. Define success criteria: Each goal must have at least one measurable or verifiable success criterion
5. Link to context: Each goal should reference why it matters (stakeholder need, incident, business driver)

Goal format:

### GOAL-0001: [Title]
- **Priority**: P0 | P1 | P2
- **Category**: Architecture | Security | Performance | Maintainability | Reliability | Observability
- **Description**: [What this goal aims to evaluate or achieve]
- **Success Criteria**:
  - [ ] [Specific, verifiable criterion]
  - [ ] [Additional criterion]
- **Context**: [Why this goal matters, who requested it]

Step 4: Identify Constraints

Document constraints that bound the review and any resulting recommendations.

1. Assign CON-NNNN IDs: Sort all constraints alphabetically by constraint text, then assign sequential four-digit numbers starting at CON-0001
2. Constraint categories:
   • Technical: Language version locks, framework commitments, platform requirements
   • Organizational: Team size, skill sets, budget, timeline
   • Business: Uptime requirements, compliance mandates, feature freeze periods
   • Contractual: SLAs, vendor agreements, licensing restrictions

Step 5: Identify Stakeholders

Document who has interest in and authority over the review outcomes.

1. Requester: Who initiated the review
2. Decision makers: Who will approve architectural changes
3. Implementers: Who will execute on recommendations
4. Affected parties: Who will be impacted by changes
5. Influence matrix: Map stakeholders to goals they care about most

Step 6: Build Alignment Matrix

Create a mapping from goals to codebase areas and analysis methods.

1. For each GOAL-NNNN, identify:

   • Codebase areas: Specific directories, files, or modules relevant to this goal
   • Analysis method: How this goal will be evaluated:
     • static-analysis: Code pattern matching, AST analysis
     • dependency-trace: Following import chains and dependency graphs
     • pattern-search: Grep-based search for anti-patterns or specific constructs
     • config-review: Examining configuration files and environment setup
     • test-coverage: Analyzing test presence, coverage, and quality
     • data-flow: Tracing data from input to storage to output
     • security-scan: Examining authentication, authorization, input validation, secrets management
   • Expected evidence type: What artifacts will demonstrate findings (code citations, metrics, diagrams)

2. Identify unmapped areas: Codebase directories or modules that are not mapped to any goal. Flag these for potential blind spots.

3. Matrix format:

| Goal ID | Codebase Area | Analysis Method | Expected Evidence |
|---------|--------------|-----------------|-------------------|
| GOAL-0001 | src/api/, src/middleware/ | dependency-trace, pattern-search | [file:line] citations |
| GOAL-0002 | src/models/, migrations/ | data-flow, config-review | Entity relationship diagram |

Step 7: Write Artifacts

Generate both output artifacts using the standard templates.

1. Write REVIEW_BRIEF.md:

   • Follow template at ${CLAUDE_PLUGIN_ROOT}/reference/templates/REVIEW_BRIEF.template.md
   • Include: Summary, Scope, Goals, Constraints, Stakeholders
   • All claims cite [file:line] evidence

2. Write ALIGNMENT_MATRIX.md:

   • Follow template at ${CLAUDE_PLUGIN_ROOT}/reference/templates/ALIGNMENT_MATRIX.template.md
   • Include: Goal-to-area mappings, analysis methods, unmapped areas, evidence expectations

Output path: artifacts/brownfield/<project_name>/REVIEW_BRIEF.md and ALIGNMENT_MATRIX.md

Output Format

REVIEW_BRIEF.md Structure

# Review Brief: [Project Name]

## Summary
[2-3 sentence overview of the review scope and purpose]

## Inputs
- Review goals provided by: [stakeholder]
- Codebase path: [path]
- Codebase language/framework: [detected stack]

## Outputs
- REVIEW_BRIEF.md (this document)
- ALIGNMENT_MATRIX.md

## Assumptions
- [ASM-NNNN]: [Assumption text with evidence]

## Open Questions
- [OQ-NNNN]: [Question text]

## Main Content

### Project Overview
[Evidence-backed description of the project]

### Review Scope
#### In Scope
#### Out of Scope
#### Depth

### Goals
[GOAL-NNNN entries]

### Constraints
[CON-NNNN entries]

### Stakeholders
[Stakeholder inventory]

## Acceptance Criteria
- [ ] All goals have GOAL-NNNN IDs assigned alphabetically
- [ ] Every goal has priority and success criteria
- [ ] Scope boundaries are explicitly defined
- [ ] Stakeholders are documented
- [ ] All codebase claims cite [file:line] evidence

ALIGNMENT_MATRIX.md Structure

# Alignment Matrix: [Project Name]

## Summary
[Purpose of this matrix]

## Inputs
- REVIEW_BRIEF.md

## Outputs
- Goal-to-codebase mapping
- Analysis method assignments
- Unmapped area inventory

## Main Content

### Goal-Area Mapping
[Table mapping goals to codebase areas]

### Analysis Methods
[Detailed method descriptions per goal]

### Unmapped Areas
[Codebase areas not covered by any goal]

### Evidence Plan
[What evidence types each goal requires]

## Acceptance Criteria
- [ ] Every GOAL-NNNN maps to at least one codebase area
- [ ] Analysis methods specified for each mapping
- [ ] Unmapped areas flagged

Determinism Rules

These rules ensure reproducible output regardless of when or how many times the skill is invoked on the same inputs.

1. GOAL-NNNN IDs: Sort all goals alphabetically by goal title (case-insensitive), then assign sequential four-digit numbers starting at 0001
2. CON-NNNN IDs: Sort all constraints alphabetically by constraint text (case-insensitive), then assign sequential four-digit numbers starting at 0001
3. ASM-NNNN IDs: Sort all assumptions alphabetically by assumption text, assign sequentially
4. OQ-NNNN IDs: Sort all open questions alphabetically by question text, assign sequentially
5. Sections: Always in template order, never reordered
6. No timestamps: Do not include generation timestamps in artifact body
7. Stable evidence: Reference file paths relative to project root, not absolute paths
8. Alignment matrix rows: Sorted by GOAL-NNNN ID, then by codebase area alphabetically

Evidence Citation Rules

Every architectural claim, observation, or assertion about the codebase MUST include evidence citations.

Format: > Claim text [relative/path/to/file.ext:line_number]

Examples:

> The project uses Express.js as its HTTP framework [package.json:8]
> Authentication middleware validates JWT tokens [src/middleware/auth.ts:15-42]
> Database connections are pooled with a max of 10 [config/database.yml:7]

Rules:

• Single line reference: [file:line]
• Range reference: [file:start-end]
• Multiple files: [file1:line] [file2:line]
• If a claim cannot be evidenced, prefix with [UNVERIFIED] and add to Open Questions

Quality Checklist

Before finalizing artifacts, verify:

• Review scope clearly defines what is in and out
• At least 2 goals with priorities assigned
• Every goal has at least one measurable success criterion
• Every goal maps to at least one codebase area in the alignment matrix
• Analysis methods specified for each goal-area mapping
• Stakeholders documented with roles
• All codebase claims cite [file:line] evidence
• GOAL-NNNN IDs are sorted alphabetically by title
• CON-NNNN IDs are sorted alphabetically by text
• No timestamps in artifact body
• Unmapped codebase areas flagged in alignment matrix
• Both artifacts follow the standard template structure

Error Handling

• No goals provided: Prompt user interactively; do not generate artifacts without at least 2 goals
• Codebase path invalid: Report error with path attempted; do not proceed
• Empty codebase: Report finding; generate minimal brief noting empty state
• Conflicting goals: Document conflict in Open Questions; assign both goals but flag dependency