---
name: "OPSX: Porting Guide"
description: Generate a detailed human-readable implementation guide for porting a feature to a target codebase
category: Workflow
tags: [workflow, portability, experimental]
---

Generate a detailed human-readable porting guide for implementing an exported feature on a target codebase.

This is a **companion** to `/opsx:export-spec`. The export-spec is optimized for AI consumption (compact, precise). This guide is optimized for the **human developer** who needs to understand context, troubleshoot issues, and make judgment calls when the AI agent on the target hits problems.

---

**Input**: The argument after `/opsx:porting-guide` is a change name or feature name that has already been exported via `/opsx:export-spec`. If omitted, prompt for selection.

**Prerequisites**: An export-spec must already exist in `openspec/exports/`. This skill reads the export-spec to stay consistent with it.

**Steps**

1. **Locate the export artifacts**

   a. Check `openspec/exports/` for matching files:
      - `<name>-spec.md` (portable spec — required)
      - `<name>-openspec.md` (OpenSpec bundle — optional)
   b. If not found, prompt with **AskUserQuestion tool**:
      > "No export-spec found for '<name>'. Available exports: [list]. Which one?"
   c. Read the export-spec fully — the porting guide must not contradict it.

2. **Read the source material**

   Same sources as export-spec, but read for **context and rationale** rather than contracts:
   a. All archived change proposals, designs, and tasks in `openspec/changes/archive/`
   b. All main specs in `openspec/specs/`
   c. The actual implementation source files
   d. Any existing export-spec and OpenSpec bundle

   Focus on extracting:
   - **Decision rationale**: WHY each design choice was made
   - **Rejected alternatives**: what was considered and discarded
   - **Friction points**: where the source implementation hit problems
   - **Implicit knowledge**: things the source developer knew but didn't document
   - **Platform traps**: runtime behaviors that aren't obvious from the code

3. **Gather target context**

   If not already captured in the export-spec, use **AskUserQuestion tool** to learn:
   > "To write accurate porting notes, I need to understand the target:
   > 1. What patterns does the target use for DI registration? (manual, Scrutor, Autofac?)
   > 2. What's the deployment model? (Azure, on-prem, Docker?)
   > 3. Are there known constraints? (network restrictions, NuGet source limits, proxy requirements?)
   > 4. Who will be implementing — developer familiarity with the source stack?"

   This shapes the level of explanation and which friction points to highlight.

4. **Generate the porting guide**

   Create a comprehensive markdown document structured for a human reader.
   Use narrative prose where it aids understanding, tables for quick reference,
   and checklists for actionable steps.

   ### Structure:

   ```markdown
   # Porting Guide: <Feature> → <Target>
   ## Source: <source project> | Export: <export-spec filename>

   ## How to Use This Guide

   Brief orientation:
   - Relationship to the AI-targeted export-spec
   - When to read this vs when to let the AI work
   - How sections are organized

   ## Architecture Overview

   2-3 paragraphs a human can read in 5 minutes to understand the full feature.
   Written as narrative, not bullet points. Cover:
   - What the feature does end-to-end (user perspective)
   - How data flows through the system (request → processing → response)
   - What external dependencies exist and why
   - The "one thing you must understand" about this feature

   ## Design Decisions (Detailed)

   For EACH significant design decision:

   ### <Decision Title>

   **What we chose:** <the approach>

   **Why:** <rationale — the real reason, not the obvious one>

   **What we rejected:**
   - <Alternative A> — rejected because <specific reason>
   - <Alternative B> — rejected because <specific reason>

   **When you'd revisit this:** <conditions under which this decision should change>

   **Target adaptation:** <how this maps to the target's patterns, what might need adjusting>

   Decisions to always cover:
   - Framework/library choices (SK over raw HTTP, SSE over WebSocket, etc.)
   - Lifetime/scope decisions (singleton vs scoped vs transient)
   - State management approach
   - Streaming strategy
   - Security decisions (sanitization, auth, CORS)
   - File/folder organization

   ## Source → Target Mapping

   Side-by-side mapping table showing how source concepts translate to target:

   | Source (ChatAgent) | Target (CRC) | Notes |
   |---|---|---|
   | `ChatAgent.Api/` | `CRC.Server/` | CRC uses hosted model, not standalone API |
   | `ChatAgent.Client/` | `CRC.Client/` | Same WASM pattern |
   | `builder.Services.AddScoped<T>()` | Check if Scrutor handles this | CRC may auto-scan |
   | ... | ... | ... |

   Flag EVERY known divergence, no matter how small. The small ones cause the most debugging time.

   ## Task-by-Task Implementation Notes

   For EACH task in the OpenSpec tasks.md:

   ### <Task ID>: <Task Title>

   **Prerequisites:** What must be completed first and verified working.

   **Context:** Why this task exists and what it accomplishes in the bigger picture.
   A developer who understands the "why" makes better judgment calls when adapting.

   **Step-by-step:**
   1. <Step with enough detail that someone unfamiliar with the source can follow>
   2. <Step>
   3. <Step>

   **Expected friction on target:**
   - <Specific thing that will likely need adaptation and why>
   - <CRC pattern that differs from the source approach>

   **Verify it works:**
   - <Concrete test: "Navigate to X, click Y, you should see Z">
   - <Log check: "Watch for 'SK: Auto-invoking function' in Serilog output">
   - <Build check: "dotnet build should produce 0 warnings related to this task">

   **If it breaks — diagnostic checklist:**
   - Symptom: <what you'll see>
     Cause: <most likely reason>
     Fix: <specific remediation>
   - Symptom: <what you'll see>
     Cause: <most likely reason>
     Fix: <specific remediation>

   ## Troubleshooting Reference

   Comprehensive symptom → cause → fix table for known porting issues.
   Organized by category (network, DI, UI, streaming, auth, config).

   | Symptom | Likely Cause | Fix |
   |---|---|---|
   | 404 on /v1/chat/completions | Base URL missing `/v1` | Add `/v1` to `NlxvaPricer:LlmBaseUrl` |
   | CORS 403 on SSE endpoint | CORS policy doesn't cover `text/event-stream` | Add origin to CORS policy |
   | Streaming hangs, no tokens | `SetBrowserResponseStreamingEnabled` missing | Add to HttpRequestMessage |
   | `EndOfStream` throws | Synchronous peek on async-only WASM stream | Use `ReadLineAsync() != null` loop |
   | Markdown not rendering | MarkdownService not registered in DI | Add `AddSingleton<MarkdownService>()` |
   | Tools never called by LLM | Plugin not imported on request | Move ImportPluginFromObject into action method |
   | ... | ... | ... |

   Include at least 10-15 entries covering the most likely failure modes.

   ## Configuration Checklist

   Every config key the feature needs, organized as a checklist:

   - [ ] `NlxvaPricer:LlmBaseUrl` — Where: `appsettings.json` (CRC.Server) — Default: `http://localhost:8317/v1` — What happens if missing: Falls back to default, fails if proxy not running
   - [ ] `NlxvaPricer:LlmModel` — Where: `appsettings.json` — Default: `claude-sonnet-4-6`
   - [ ] ... (every key)

   ## Dependency & Package Notes

   For each new package:
   - Package name and version constraint
   - Why it's needed (one sentence)
   - .NET version compatibility notes
   - Known conflicts with packages the target might already have
   - NuGet source: public nuget.org or internal feed?
     (CRC uses internal GV Artifactory — flag if a package might not be available there)

   ## Rollback Plan

   If the feature needs to be removed:
   - Which files were added (safe to delete)
   - Which files were modified and what was added (revert specific sections)
   - Which NuGet packages were added (remove from csproj)
   - Which config keys were added (remove from appsettings.json)
   ```

5. **Cross-check against export-spec**

   Before writing, verify:
   - Every contract in the export-spec is explained in the porting guide
   - Every critical pattern has a troubleshooting entry
   - No contradictions between the two documents
   - The porting guide adds CONTEXT, not ALTERNATIVE instructions

6. **Write the output**

   Save to: `openspec/exports/<name>-porting-guide.md`
   Display a summary of sections generated and key highlights.

**Guardrails**

- **Narrative over telegraphic**: This is for humans. Use complete sentences. Explain the "why."
- **Never contradict the export-spec**: The AI spec is the source of truth for contracts and patterns. The porting guide explains and contextualizes, it doesn't override.
- **Anticipate the debugging session**: For every task, imagine the developer hitting a wall. What would they need to know? Write that down.
- **Be specific about the target**: Generic advice ("check your config") is useless. Specific advice ("CRC uses `gv_web_config.csv` for primary config but `appsettings.json` for secondary — LLM config goes in appsettings") saves hours.
- **Include the embarrassing details**: The things that took 30 minutes to figure out in the source (like the `/v1` URL requirement, or `EndOfStream` hanging) — those are the most valuable entries.
- **Flag NuGet source issues**: If the target uses an internal feed (like CRC's GV Artifactory with nuget.org disabled), flag every package that needs to come from a specific source.
- **No code blocks for code's sake**: The export-spec has the exact code. The porting guide references it ("see Critical Pattern #2 in the export-spec") rather than duplicating it. Only include code when it clarifies a specific porting concern.
- **Version-stamp the guide**: Include the date and source commit hash so the reader knows what state the guide reflects.

**Anti-patterns**

1. **Don't duplicate the export-spec.** The export-spec has exact contracts and code snippets. The porting guide has context, rationale, and troubleshooting. They complement each other.

2. **Don't be abstract.** "There might be DI issues" is useless. "CRC uses Scrutor for assembly scanning. If Scrutor auto-registers ExtractionPlugin before your manual AddScoped<ExtractionPlugin>(), you'll get a duplicate registration. Check with `builder.Services.Where(s => s.ServiceType == typeof(ExtractionPlugin))` in a breakpoint" is useful.

3. **Don't skip the obvious.** The developer may be senior but unfamiliar with Semantic Kernel. Explain SK concepts (Kernel, plugins, FunctionChoiceBehavior) in plain language.

4. **Don't assume the happy path.** Network restrictions, proxy requirements, package feed limitations, and auth quirks are the norm in enterprise environments. Address them.

ARGUMENTS: $ARGUMENTS