Strategic Direction

When you add certain markdown files to your repository, Superpositional uses their content to contextualise PR reviews and repo summaries. Instead of just telling you whether a change is correct, it tells you whether the change aligns with your team's stated direction.

This is entirely convention-based. Drop a file in your repo, and it works. No configuration UI, no setup steps.

How it works

During indexing, Superpositional identifies files that describe your team's direction, architecture intent, or product goals. When reviewing a PR, it retrieves the most relevant strategic content for that PR's domain and includes it as context in the review synthesis. A PR touching payment code gets payment-related direction. A CSS fix gets nothing — strategic context is only included when it's relevant.

Setting it up

Add a markdown file to your repository. Superpositional recognizes these conventions:

You can use any of these. DIRECTION.md at the repo root is the most explicit signal — it tells the system "this is what we care about, use it."

Files matching these conventions get a relevance boost during retrieval, but any indexed markdown content can contribute to strategic context if it's semantically relevant to a PR.

What changes in reviews

When strategic content is relevant to a PR, the review includes a "Strategic Context" note. This note is informational — it does not affect the verdict (approve, concerns, reject) and does not block merging.

A strategic context note looks like:

Strategic context: Your DIRECTION.md states you're moving toward event-driven communication between services. This PR adds a direct synchronous call from PaymentHandler to AuthService. Consider whether an event-based approach would serve both the timeout fix and the long-term architecture direction.

When strategic content exists but isn't relevant to the PR's domain, nothing is added. There's no generic placeholder or "no strategic concerns" message.

Example DIRECTION.md

A good direction document is short and specific. It states where you're going, what you're leaving behind, and what the product does. Here's a template:

# Direction

## Where we're going
- Event-driven architecture between all services
- Each service owns its data store exclusively
- Contract-first API design

## What we're moving away from
- Shared database access between services
- Synchronous service-to-service calls
- Manual deployment processes

## Product
Real-time payment processing for marketplace sellers.

Tips for writing a useful direction document:

• Be specific. "Better architecture" is too vague to act on. "Event-driven communication between services" gives the system something concrete to compare against.
• Include both directions. Stating what you're moving away from is as useful as stating where you're going — it helps identify when a PR reintroduces a pattern you've explicitly decided to leave behind.
• Keep it short. A few bullet points per section is enough. The system retrieves the most relevant chunks, so a focused document produces better signal than a long one.
• Update it when decisions change. The file is versioned with your code. When your direction shifts, update the file and future reviews reflect the new direction.

What changes in repo summaries

When strategic content is present, the repo summary includes a strategic_direction section capturing:

• Stated direction — what explicit direction documents say (highest confidence)
• Inferred goals — what the system infers from ADRs, README, and architecture docs (lower confidence)
• Moving toward / moving away from — directional patterns extracted from your docs
• Product value proposition — what the product does for users

This information surfaces in the list_repos MCP tool response and the repo overview, giving you and your AI tools a quick understanding of what a repo aims to do — not just what it currently is.

What happens without a direction document

Nothing changes. Reviews work as normal. The system can still infer some direction from ADRs, README content, and architecture docs, but explicit direction documents give the strongest signal and produce the most specific strategic context in reviews.

MCP tools

Strategic direction context also surfaces in MCP tool responses:

• review_plan — when you describe a plan, the response considers whether it aligns with your team's stated direction.
• system_context — when you look up context for an entity, relevant strategic direction is included if the entity falls in a domain covered by your direction docs.

No separate tool or configuration is needed. Strategic content is retrieved through the same paths that power all other contextual information.