Architecture Context Reviewer

Contributed by: Mark Whaley · Source: PM Starter Kit

Use this when a PM needs to ground a feature's technical signals in real architecture — actual services, databases, event streams, and owning teams — before any code or dependency analysis happens. Takes the systems and data entities from /technical-intent-parser and retrieves verified context from architecture docs, ADRs, service catalogs, and diagrams.

This skill prevents hallucination by forcing a lookup of reality before downstream analysis. It sits in the Feature Impact Radar pipeline: /technical-intent-parser → /architecture-context-reviewer → /repository-discovery → /codependency-analyzer.

Process

Step 1: Gather inputs

Ask the user:

1. Systems involved — The system domains identified by /technical-intent-parser (e.g., billing, notifications, user_preferences). If coming from the pipeline, these are already available.
2. Data entities — The business objects identified by /technical-intent-parser (e.g., invoice, reminder_preferences, user).
3. Architecture sources — Where should I look? Provide links or names for any of:
   • Service catalog / registry (Backstage, Cortex, etc.) — preferred source of truth
   • ADR repository
   • Architecture documentation portal or wiki
   • System diagrams (C4, sequence diagrams)
   • Event catalog / schema registry
   • Data catalog
4. Org context (optional) — Monorepo or polyrepo? Cloud provider? Domain naming conventions?

If systems and data entities are missing, stop and request them (or run /technical-intent-parser first).

Step 2: Identify which personas are affected

Before generating the context review, prompt the user:

Persona check: Which user persona(s) does this feature affect? If you have defined personas (e.g., from /persona-create or /persona-draft), name them. If not, describe who uses the features powered by these systems.

This connects architecture context to real user journeys and ensures the review highlights what matters to product decisions.

Step 3: Build a query set and search

Derive search queries from:

• Each entry in systems involved
• Each entry in data entities
• Any possible services (if provided)
• Synonyms (e.g., "user_preferences" → "settings", "preferences")

Create 6–12 queries total (3–5 system-level, 3–5 entity-level, 1–2 cross terms).

Source priority order (highest to lowest):

1. Service catalog / registry
2. Event catalog / schema registry
3. Data catalog
4. ADRs
5. Architecture docs / system overviews
6. Diagrams
7. Wiki pages / team notes

Search across prioritized sources. Open top results and extract service names, databases, event streams, and ownership. Cross-check at least 2 sources when possible. If sources conflict, prefer higher-authority sources and note the conflict.

Step 4: Extract and normalize architecture facts

Present the verified context:

## Architecture Context — (Feature Name)

**Date:** (Date)
**Sources reviewed:** (List of sources checked)
**Confidence level:** (High / Medium / Low — based on source completeness)

---

### Verified Services

| Service | Responsibility | Source |
|---|---|---|
| (service-name in kebab-case) | (What it does) | (Where this was confirmed) |

### Databases & Datastores

| Database | Contains | Owning service | Source |
|---|---|---|---|
| (db_name in snake_case) | (Key entities stored) | (Service that owns it) | (Source) |

### Event Streams

| Event / Topic | Producer | Consumer(s) | Source |
|---|---|---|---|
| (event.name) | (Service that publishes) | (Service(s) that subscribe) | (Source) |

### Service Owners

| Service | Owning team | Contact channel |
|---|---|---|
| (service-name) | (team slug, e.g., payments-team) | (Slack channel, on-call rotation) |

Step 5: Flag gaps and open questions

### Evidence Gaps

- (What couldn't be verified and why — e.g., "No service catalog entry found for user-preferences-service")
- (Missing source — e.g., "Event catalog not available; event streams are inferred from ADR-047")

### Questions for the Team

1. (Question about a gap — e.g., "Where is the source of truth for event stream contracts?")
2. (Question about ambiguity — e.g., "Is notification-service the same as messaging-platform in the docs?")
3. (Question about ownership — e.g., "Who owns the user_settings_db — identity-team or growth-platform?")

Step 6: Review and validate

Ask the user:

• Does this match what you know about the architecture?
• Are there services, databases, or event streams I missed?
• Are the ownership mappings correct?
• Ready to proceed to /repository-discovery with these verified services?

Adjust as needed.

Related skills

• /technical-intent-parser — upstream: provides the systems and entities that this skill grounds in real architecture.
• /repository-discovery — next step: maps verified services to code repositories and maintainers.
• /codependency-analyzer — downstream: extracts evidence-based code dependencies.
• /context-packet — when you need broader project context beyond architecture.
• /stakeholder-map — when you need to map the people who own these services.

Output location

Present the verified context tables, evidence gaps, and questions as formatted text in the conversation. The output feeds directly into /repository-discovery and downstream pipeline skills. The user may also use it as a standalone architecture briefing for onboarding or planning.