---
name: gsd:openlore-orient
description: Pre-phase structural risk check via openlore MCP — orient + analyze_impact before execute-phase. Writes .planning/codebase/RISK-CONTEXT.md.
argument-hint: "[phase number or task description]"
allowed-tools:
  - mcp__openlore__orient
  - mcp__openlore__analyze_impact
  - mcp__openlore__search_specs
  - mcp__openlore__analyze_codebase
  - Read
  - Write
  - Glob
---

<objective>
Run openlore structural analysis before executing a phase. Identify high-risk functions,
surface relevant spec requirements, and gate on riskScore ≥ 70 before any code is written.

Output: `.planning/codebase/RISK-CONTEXT.md` with structural risk summary for the phase.
</objective>

<when_to_use>
Run this command:
- Before `/gsd:execute-phase` on a brownfield codebase
- After `/gsd:plan-phase` when the plan touches existing code
- Any time you suspect a planned change touches a high-fan-in function

Skip this command:
- Greenfield projects with no existing codebase (nothing to analyse)
- Trivial changes (config edits, documentation only)
</when_to_use>

<prerequisites>
1. openlore MCP server configured in Claude Code settings
2. `openlore analyze` run at least once on this project
   If not: this command will detect the missing cache and offer to run it.
</prerequisites>

<process>

<step name="load_context">
Load current project state:

```bash
cat .planning/STATE.md 2>/dev/null || echo "No STATE.md found"
```

Determine the active phase and extract the implementation intent from:
- `.planning/phases/PHASE-{N}-PLAN.md` if a phase number was provided or is active
- `$ARGUMENTS` if a task description was provided directly

If neither exists, ask the user: "What are you about to implement?"
Use the answer as `$TASK_DESCRIPTION`.
</step>

<step name="check_cache">
Run orient to verify cache exists:

```
openlore orient
  directory: $PROJECT_ROOT
  task: $TASK_DESCRIPTION
  limit: 7
```

If orient returns `"error": "no cache"`:
> openlore has no analysis cache for this project.
> Run `openlore analyze $PROJECT_ROOT` first (takes ~1 min for most projects).
> Then re-run `/gsd:openlore-orient`.

Offer to run analysis now:
```
openlore analyze_codebase
  directory: $PROJECT_ROOT
```
Wait for completion, then proceed.
</step>

<step name="check_spec_baseline">
Check whether OpenSpec specifications exist:

```bash
ls $PROJECT_ROOT/openspec/specs/ 2>/dev/null | head -5
```

**If no specs exist** (`openspec/specs/` absent or empty):
> "No OpenSpec specs found for this project. `search_specs` will return empty results
> and `check_spec_drift` will flag all files as uncovered.
>
> Recommended: run `openlore generate $PROJECT_ROOT` after this phase to create a spec
> baseline. You only need to do this once — future phases will benefit from spec alignment.
>
> Continuing with structural analysis only (orient + impact)."

Skip the search_specs step below and go straight to impact_analysis.

**If specs exist**: proceed to search_specs.
</step>

<step name="search_specs">
Surface existing requirements that apply to this change:

```
openlore search_specs
  directory: $PROJECT_ROOT
  query: $TASK_DESCRIPTION
  limit: 5
```

List any relevant requirements found. Note constraints that apply to the planned implementation.
If search returns no results despite specs existing, note it in RISK-CONTEXT.md under
"Relevant Spec Requirements: none matched — area may not be spec'd yet".
</step>

<step name="impact_analysis">
For the top 2 functions returned by orient, run impact analysis:

```
openlore analyze_impact
  directory: $PROJECT_ROOT
  symbol: $FUNCTION_NAME
  depth: 2
```

Build a risk table:

| Function | File | Risk Score | Level | Callers |
|----------|------|-----------|-------|---------|
</step>

<step name="gate">
Apply the risk gate:

| Max risk score | Decision |
|---|---|
| < 40 | 🟢 Proceed — show insertion points, write RISK-CONTEXT.md |
| 40–69 | 🟡 Proceed with caution — list callers to protect in RISK-CONTEXT.md |
| ≥ 70 | 🔴 **Stop.** Do not execute phase until the blocking function is refactored. |

**If riskScore ≥ 70 on any function:**

> ⚠️ High structural risk on `$FUNCTION_NAME` (score: $SCORE, $CALLER_COUNT callers).
>
> Recommended: add a refactor plan to the current phase or insert a new phase before this one.
> Use `/gsd:insert-phase` to add a refactor phase, then re-run `/gsd:openlore-orient`.

Stop and wait for user decision. Do not proceed to execute-phase.
</step>

<step name="write_output">
Write `.planning/codebase/RISK-CONTEXT.md`:

```markdown
# Risk Context — Phase {N}

> Generated by openlore on {date}. Re-run `/gsd:openlore-orient` after structural changes.

## Summary

- **Phase intent**: {task_description}
- **Domains**: {domains}
- **Max risk score**: {score} {badge}
- **Decision**: {🟢 proceed | 🟡 proceed with caution | 🔴 blocked}

## Functions in Scope

| Function | File | Risk | Hub |
|----------|------|------|-----|
{rows}

## Callers to Protect

{list of callers from impact analysis, or "none"}

## Blocking Refactors

{list of functions with risk ≥ 70, or "none"}

## Relevant Spec Requirements

{list from search_specs, or "none found — run openlore generate to create specs"}

## Insertion Points

{top insertion point from orient}
```

Confirm: "Risk context written to `.planning/codebase/RISK-CONTEXT.md`. Safe to run `/gsd:execute-phase`."
</step>

</process>
