/nav-sop

name: nav-sop
description: Create Standard Operating Procedures after solving novel issues, establishing patterns, or documenting workflows. Use when user says "document this solution", "save this for next time", "create SOP".
allowed-tools: Read, Write, Bash
version: 1.0.0

Navigator SOP Creator Skill

Create Standard Operating Procedures (SOPs) - reusable documentation for processes, integrations, debugging solutions, and workflows.

When to Invoke

Invoke this skill when the user:

• Says "document this solution", "save this for next time"
• Says "create SOP", "make this reusable"
• Solves a novel issue and mentions "don't want to hit this again"
• Sets up integration and says "document the setup"
• Establishes pattern and mentions "team should follow this"

**DO NOT invoke** if:

• Creating task documentation (use nav-task skill)
• Updating architecture docs (different purpose)
• Simple bug fix with no reusable pattern

Execution Steps

Step 1: Determine SOP Category

Ask user which category (or infer from context):

**Categories**: 1. **integrations** - Third-party service setups 2. **debugging** - Common issues & solutions 3. **development** - Dev workflows, patterns 4. **deployment** - Deploy procedures, CI/CD

**Examples**:

• "How to set up Stripe webhooks" → `integrations/`
• "Fixing CORS errors" → `debugging/`
• "Testing authenticated routes" → `development/`
• "Deploy to production" → `deployment/`

Step 2: Determine SOP Name

**If user provided name**:

• Use their name (sanitize: lowercase, hyphens)
• Example: "Stripe Payment Setup" → "stripe-payment-setup"

**If no name provided**:

• Generate from context: `{service}-{action}`
• Example: "github-oauth-integration"
• Example: "cors-proxy-errors"

Step 3: Check if SOP Already Exists

Check existing SOPs in category:

ls .agent/sops/{category}/*.md 2>/dev/null

**If similar SOP exists**:

⚠️  Similar SOP found:
   .agent/sops/{category}/{similar-name}.md

Options:
1. Read existing SOP (don't duplicate)
2. Update existing SOP (add to it)
3. Create new SOP (different enough)

Your choice [1-3]:

Step 4: Generate SOP Content

Create SOP document from conversation:

# {SOP Title}

**Category**: {integrations|debugging|development|deployment}
**Created**: {YYYY-MM-DD}
**Last Updated**: {YYYY-MM-DD}

---

## Context

**When to use this SOP**:
[Describe the scenario where this applies]

**Problem it solves**:
[What issue does this address?]

**Prerequisites**:
- [Requirement 1]
- [Requirement 2]

---

## The Problem

### Symptoms
[What does the issue look like?]
- Error message: `{specific error}`
- Behavior: [Unexpected behavior]
- Impact: [What breaks]

### Root Cause
[Why does this happen? Technical explanation]

---

## The Solution

### Step 1: {Action}

**Do this**:
```bash
# Command or code
npm install stripe

**Why**: [Explanation of what this accomplishes]

**Expected output**:

+ stripe@12.0.0
added 1 package

Step 2: {Next Action}

**Do this**:

// Code example
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

**Why**: [Explanation]

**Configuration**: Add to `.env`:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Step 3: {Continue...}

...

---

Complete Example

Full Working Code

**File**: `src/services/stripe.ts`

import Stripe from 'stripe';

export class StripeService {
  private stripe: Stripe;

  constructor() {
    this.stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
      apiVersion: '2023-10-16',
    });
  }

  async createPaymentIntent(amount: number) {
    return await this.stripe.paymentIntents.create({
      amount: amount * 100, // Convert to cents
      currency: 'usd',
    });
  }
}

**File**: `src/routes/webhook.ts`

export async function handleStripeWebhook(req: Request, res: Response) {
  const sig = req.headers['stripe-signature'];

  try {
    const event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    // Handle event
    switch (event.type) {
      case 'payment_intent.succeeded':
        // Process successful payment
        break;
    }

    res.json({ received: true });
  } catch (err) {
    res.status(400).send(`Webhook Error: ${err.message}`);
  }
}

---

Testing

Verify It Works

**Test 1: Create payment intent**

curl -X POST http://localhost:3000/api/create-payment \
  -H "Content-Type: application/json" \
  -d '{"amount": 10}'

**Expected result**:

{
  "clientSecret": "pi_xxx_secret_yyy"
}

**Test 2: Webhook delivery**

stripe listen --forward-to localhost:3000/webhook

**Expected result**:

Ready! You are using Stripe API Version [2023-10-16]

---

Prevention

**How to avoid this issue in future**:

• [Prevention strategy 1]
• [Prevention strategy 2]

**Red flags to watch for**:

• [Warning sign 1]
• [Warning sign 2]

---

Troubleshooting

Issue: Webhook signature verification fails

**Symptoms**:

Error: No signatures found matching the expected signature

**Cause**: Webhook secret mismatch or body already parsed

**Fix**:

// Use raw body for webhook verification
app.post('/webhook', express.raw({type: 'application/json'}), handleStripeWebhook);

Issue: Payment amount incorrect

**Symptoms**: Charged wrong amount

**Cause**: Forgot to convert to cents

**Fix**: Always multiply by 100 for Stripe amounts

---

Related Documentation

**Stripe Docs**:

• [Payment Intents API](https://stripe.com/docs/api/payment_intents)
• [Webhooks Guide](https://stripe.com/docs/webhooks)

**Our Docs**:

• Task: `.agent/tasks/TASK-04-stripe-integration.md`
• System: `.agent/system/project-architecture.md` (payments section)

**External**:

• [Stripe Testing Cards](https://stripe.com/docs/testing)

---

Maintenance Notes

**Update when**:

• Stripe API version