---

name: aip-code-correlator description: This skill should be used when the user asks "where is this API endpoint implemented", "find the code for this route", "which file handles this endpoint", "map API findings to code", or needs to correlate OpenAPI spec paths with source code locations. Also use when creating fix plans for code-first API projects (NestJS, Fastify, Express) after running aip-review, or when user mentions "find my NestJS controller", "locate Fastify route handler", "Express route definition".

AIP Code Correlator

Map AIP review findings to code locations for code-first API projects.

Preferred Approach: MCP Correlate Tool

IMPORTANT: If the mcp__aip-reviewer__aip-correlate tool is available, use it instead of manual correlation. The MCP tool:

• Takes a reviewId from aip-review
• Automatically detects framework from package.json
• Uses MCP sampling for accurate code location
• Batch processes all findings efficiently
• Returns ExtendedFinding[] with file:line references

CopyUse mcp__aip-reviewer__aip-correlate with:
- reviewId: {review-id-from-aip-review}
- projectRoot: {absolute-path-to-project}
- specPath: {absolute-path-to-spec} (optional, for context extraction)
- framework: "nestjs" | "fastify" | "express" | "unknown" (optional hint)
- correlationLevel: "minimal" | "moderate" | "thorough" (optional, default: "moderate")

The manual process below is a fallback for when MCP tools are not available.

When to Use (Manual Fallback)

This skill activates when:

• Creating a fix plan after aip-review for a code-first project
• User asks "where is this endpoint implemented?"
• User wants to fix API issues and needs to know which files to modify
• Mapping OpenAPI spec paths to source code
• MCP correlate tool is not available

Prerequisites

• AIP review findings (from aip-review MCP tool or review document)
• Access to project source code
• OpenAPI spec (to extract operation context)

Correlation Process

Step 1: Gather Inputs

From MCP tool results: If aip-review was called, use the findings from that response.

From review document: If working from thoughts/api/reviews/*.md, read the document to get:

• spec_path from frontmatter
• Findings list with ruleId, path, severity

Step 2: Extract Operations from Findings

Parse each finding's path field to extract method and API path:

Copy"GET /users/{id}" → method: GET, path: /users/{id}
"POST /orders"    → method: POST, path: /orders

Dedupe by method+path (multiple findings may target same endpoint).

Step 3: Detect Framework

Read package.json in project root:

• @nestjs/core → NestJS (decorators: @Controller, @Get, @Post)
• fastify → Fastify (route methods: .get, .post, app.route)
• express → Express (router methods: router.get, app.get)

Step 4: Find Code Locations

For each unique operation, spawn an aip-code-locator agent:

CopyTask: aip-code-locator
Prompt: Find the code that implements this API operation:
  - method: GET
  - path: /users/{id}
  - operationId: getUserById (if available from spec)
  - framework: nestjs
  - rootDir: /project

Spawn up to 5 agents in parallel for efficiency.

Step 5: Compile Extended Findings

For each finding, build this structure:

Copy{
  "finding": {
    "ruleId": "aip122/plural-resources",
    "severity": "warning",
    "path": "GET /user/{id}",
    "message": "Resource name should be plural",
    "suggestion": "Rename to /users/{id}",
    "fix": { "type": "rename-path-segment", "..." }
  },
  "specContext": {
    "method": "GET",
    "path": "/user/{id}",
    "operationId": "getUser",
    "summary": "Get a user by ID",
    "tags": ["users"]
  },
  "codeLocations": [
    {
      "file": "src/users/users.controller.ts",
      "line": 42,
      "type": "controller",
      "confidence": "high",
      "snippet": "@Get(':id')\nasync getUser(@Param('id') id: string) { ... }",
      "reasoning": "@Get decorator matches, operationId in @ApiOperation"
    }
  ],
  "suggestedDiffs": {
    "specDiff": "...",
    "codeDiffs": [{ "file": "...", "diff": "...", "description": "..." }]
  }
}

Step 6: Generate Suggested Diffs

For deterministic fixes, pre-populate code diffs using templates from diff-templates.md.

Step 7: Output Correlation

Write to thoughts/api/correlations/{date}-{spec-name}.json:

Copy{
  "extendedFindings": [
    /* ... */
  ],
  "framework": "nestjs",
  "generatedAt": "2025-01-15T10:30:00Z",
  "reviewPath": "thoughts/api/reviews/...",
  "specPath": "openapi.yaml",
  "summary": {
    "correlated": 6,
    "notFound": 2,
    "totalFindings": 8
  }
}

Output Format

Report results to user:

Copy## Correlation Complete

| Operation       | Code Location                      | Confidence |
| --------------- | ---------------------------------- | ---------- |
| GET /users/{id} | src/users/users.controller.ts:42   | high       |
| POST /users     | src/users/users.controller.ts:28   | high       |
| GET /orders     | src/orders/orders.controller.ts:15 | medium     |

**Not found:** DELETE /admin/cache, GET /health

Correlation saved to: thoughts/api/correlations/2025-01-15-orders-api.json

MCP Tools Reference

aip-review: Analyze OpenAPI spec against AIP rules. Returns findings with reviewId.

CopyCall: mcp__aip-reviewer__aip-review with specPath or specUrl
Returns: { reviewId, findings[], summary, findingsPath, findingsUrl }

aip-correlate: Correlate AIP review findings with code locations.

CopyCall: mcp__aip-reviewer__aip-correlate with reviewId, projectRoot, specPath, framework
Returns: { extendedFindings[], framework, summary, correlationPath }

aip-apply-fixes: Apply suggested fixes to spec (after correlation, to fix spec issues).

CopyCall: mcp__aip-reviewer__aip-apply-fixes with reviewId, specPath/specUrl, writeBack, dryRun
Returns: { summary, downloadUrl, modifiedSpec }

Agent Reference

aip-code-locator: Find code implementing a single API operation.

• Input: method, path, operationId, tags, rootDir, framework
• Output: CodeLocation[] with file:line, confidence, snippets

File Locations

Related

• Use /api-plan after correlation to create a fix plan
• Use /api-validate to verify fixes against the plan
• Use aip-code-locator agent directly for single operation lookup
• See aip-knowledge skill for AIP rule explanations