Code migration documentation and technical debt assessment

Introduction

Code migration is a fact of life for growing engineering teams, but it's also one of the most tedious and error-prone processes you'll encounter. You're dealing with dozens or hundreds of files, inconsistent documentation, legacy patterns that nobody quite remembers, and technical debt that compounds with every line you don't migrate. The problem gets worse when you need to assess that debt at the same time: what actually needs to go, what can stay, and what should be refactored first?

Most teams handle this manually. Someone exports a codebase list, someone else runs static analysis tools, a third person updates documentation in Markdown files, and a fourth person tries to manually correlate all of this into something resembling a coherent picture. Each handoff introduces delays, information loss, and the real risk that your assessment becomes outdated before you even finish it. The result is a migration plan that's incomplete, inconsistent, and difficult to track.

This workflow shows you how to automate the entire pipeline: from burning through a codebase with Burnrate to generate debt metrics, through using Windsurf to actually migrate code and generate improvement suggestions, and finally publishing everything as searchable, properly structured documentation in Mintlify. We'll wire it all together with n8n so the only manual step is kicking off the initial scan.

The Automated Workflow

We're going to build this in n8n because it gives us proper conditional logic, file handling, and direct integration with all three tools without needing intermediate API transformation layers. The workflow runs in four stages: analysis, code migration, documentation generation, and publication.

Stage 1: Run Burnrate Analysis

Start by triggering a Burnrate scan on your codebase. Burnrate analyses code for technical debt by examining metrics like cyclomatic complexity, code duplication, dependency management issues, and outdated patterns. You'll need to authenticate with your Burnrate account and point it at a specific repository.

Create an n8n workflow and add an HTTP Request node as your first step. Configure it like this:

Copy
Method: POST
URL: https://api.burnrate.dev/v1/scans
Headers:
  Authorization: Bearer YOUR_BURNRATE_API_KEY
  Content-Type: application/json
Body (JSON):
{
  "repository_url": "https://github.com/yourusername/yourrepo",
  "branch": "main",
  "language": "typescript",
  "include_patterns": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude_patterns": ["node_modules/**", "dist/**", "*.test.ts"]
}

Replace the placeholder values with your actual repository URL and Burnrate API key (which you'll find in your Burnrate dashboard under Settings). This request kicks off an asynchronous scan, and Burnrate will return a scan ID that you'll use to poll for results.

Store that scan ID in an n8n variable so you can reference it in the next step. Add a Set node and configure it to extract the scan ID from the response:

Copy
Variable name: burnrate_scan_id
Value: {{ $node["HTTP Request"].json.data.id }}

Wait for the scan to complete by adding a polling mechanism. Use another HTTP Request node set to GET mode that checks the scan status every 30 seconds for up to 10 minutes:

Copy
Method: GET
URL: https://api.burnrate.dev/v1/scans/{{ $variables.burnrate_scan_id }}
Headers:
  Authorization: Bearer YOUR_BURNRATE_API_KEY
Polling: enabled, 30 second interval, 20 attempts max

Burnrate will return a report with metrics across multiple categories. The response includes fields like:

Copy{
  "id": "scan_abc123",
  "status": "completed",
  "metrics": {
    "cyclomatic_complexity": 3.2,
    "code_duplication": 12.5,
    "maintainability_index": 65,
    "outdated_dependencies": 8,
    "test_coverage": 72,
    "vulnerability_count": 2
  },
  "files_analysed": 156,
  "issues": [
    {
      "file": "src/api/handler.ts",
      "type": "high_complexity",
      "severity": "high",
      "details": "Function processPayment has cyclomatic complexity of 14"
    }
  ]
}

Stage 2: Generate Code Migration with Windsurf

Now you've got a detailed picture of what needs fixing. Feed this report into Windsurf, which uses advanced language models to not just identify issues but actually generate migration code and refactoring suggestions. Windsurf works through a chat-based API where you send context and instructions, and it returns generated code and analysis.

Add another HTTP Request node to trigger Windsurf:

Copy
Method: POST
URL: https://api.windsurf.dev/v1/chat/completions
Headers:
  Authorization: Bearer YOUR_WINDSURF_API_KEY
  Content-Type: application/json
Body (JSON):
{
  "model": "windsurf-code-migration",
  "messages": [
    {
      "role": "system",
      "content": "You are an expert code migration assistant. Analyse technical debt reports and generate specific migration code, refactoring suggestions, and migration plans."
    },
    {
      "role": "user",
      "content": "Based on this technical debt report, generate a prioritised migration plan with code examples for each issue:\n\n" + JSON.stringify($node["HTTP Request1"].json.metrics) + "\n\nFor each high-severity issue, provide:\n1. Current problematic code pattern\n2. Refactored code solution\n3. Migration steps\n4. Risk assessment"
    }
  ],
  "temperature": 0.3,
  "max_tokens": 4000
}

Set the temperature to 0.3 (lower temperature means more focused, deterministic output) since you want reliable code suggestions, not creative experiments. Windsurf will respond with a structured migration plan that includes actual code snippets you can use.

Store the migration plan in another variable:

Copy
Variable name: migration_plan
Value: {{ $node["HTTP Request2"].json.choices[0].message.content }}

Stage 3: Generate Documentation with Mintlify

Mintlify is a documentation-as-code platform that converts Markdown into beautifully formatted docs with search, navigation, and versioning built in. Rather than having developers manually document the migration, you're going to generate that documentation automatically from your analysis and migration plan.

Create a new HTTP Request node that calls the Mintlify API:

Copy
Method: POST
URL: https://api.mintlify.com/v1/docs/generate
Headers:
  Authorization: Bearer YOUR_MINTLIFY_API_KEY
  Content-Type: application/json
Body (JSON):
{
  "project_id": "your-project-id",
  "content": {
    "title": "Code Migration Plan and Technical Debt Assessment",
    "date": new Date().toISOString(),
    "sections": [
      {
        "name": "Executive Summary",
        "content": "Technical debt assessment completed on {{ new Date().toLocaleDateString() }}. Total issues identified: {{ $node["HTTP Request1"].json.issues.length }}. Estimated remediation time: {{ calculateRemediationTime($node["HTTP Request1"].json.metrics) }} hours."
      },
      {
        "name": "Debt Metrics Overview",
        "content": formatMetricsTable($node["HTTP Request1"].json.metrics)
      },
      {
        "name": "Prioritised Migration Plan",
        "content": {{ $variables.migration_plan }}
      },
      {
        "name": "High-Severity Issues",
        "content": formatIssuesDetail($node["HTTP Request1"].json.issues.filter(i => i.severity === "high"))
      }
    ]
  }
}

This won't work as a literal copy-paste because the API varies slightly. Instead, the actual approach is to construct a Markdown file and push it to Mintlify. Add a File Write node in n8n:

Copy
File path: /tmp/migration_report.md
Content:
Generated: {{ new Date().toLocaleDateString() }}

## Executive Summary

This assessment identified {{ $node["HTTP Request1"].json.files_analysed }} files and {{ $node["HTTP Request1"].json.issues.length }} issues requiring attention.

### Key Metrics

- **Cyclomatic Complexity**: {{ $node["HTTP Request1"].json.metrics.cyclomatic_complexity }} (target: < 5)
- **Code Duplication**: {{ $node["HTTP Request1"].json.metrics.code_duplication }}% (target: < 5%)
- **Maintainability Index**: {{ $node["HTTP Request1"].json.metrics.maintainability_index }}/100
- **Test Coverage**: {{ $node["HTTP Request1"].json.metrics.test_coverage }}%
- **Outdated Dependencies**: {{ $node["HTTP Request1"].json.metrics.outdated_dependencies }}
- **Vulnerabilities**: {{ $node["HTTP Request1"].json.metrics.vulnerability_count }}

## Prioritised Migration Plan

{{ $variables.migration_plan }}

## High-Severity Issues

{{ formatHighSeverityIssues($node["HTTP Request1"].json.issues) }}

Then use another HTTP Request to commit this to your Mintlify repository:

Copy
Method: POST
URL: https://api.github.com/repos/YOUR_MINTLIFY_REPO/contents/docs/migration-report.md
Headers:
  Authorization: token YOUR_GITHUB_TOKEN
  Content-Type: application/json
Body (JSON):
{
  "message": "Update migration report from automated scan",
  "content": "{{ Buffer.from(readFileSync('/tmp/migration_report.md')).toString('base64') }}",
  "branch": "main"
}

Stage 4: Trigger Mintlify Build and Publish

Mintlify watches your repository and rebuilds automatically, but you can trigger a rebuild via webhook to ensure documentation is live immediately:

Copy
Method: POST
URL: https://api.mintlify.com/v1/docs/rebuild
Headers:
  Authorization: Bearer YOUR_MINTLIFY_API_KEY
  Content-Type: application/json
Body (JSON):
{
  "project_id": "your-project-id"
}

That's the complete pipeline. When you run this workflow, it will:

1. Scan your codebase with Burnrate (takes 2-5 minutes depending on size)
2. Pass the results to Windsurf for intelligent migration planning (takes 30-60 seconds)
3. Generate beautifully formatted documentation with Mintlify (takes 10-15 seconds)
4. Publish the docs live (takes 20-30 seconds)

The entire process runs with zero manual handoff between stages. Data flows directly from tool to tool, and you end up with both a migration plan and up-to-date documentation.

The Manual Alternative

If you prefer more control over each stage, you can run these tools independently and review output before proceeding.

Run Burnrate locally using their CLI:

Copy
burnrate scan --repository . --language typescript --output burnrate-report.json

Review the report, then manually prompt Windsurf through their web interface with the report attached. Copy the generated migration plan.

Use the Mintlify CLI to build documentation locally before publishing:

Copy
mintlify dev

This lets you preview the documentation in your browser, make edits to the Markdown, and publish only when satisfied. For small codebases or if you're doing this infrequently, this approach gives you more visibility into what's happening at each stage, though it does reintroduce manual handoff points.

Pro Tips

Use scheduled workflows instead of manual triggers. Set up the n8n workflow to run on a weekly schedule (Monday morning is traditional). This means your technical debt assessment and migration documentation stay current automatically. Configure it in the n8n workflow settings by adding a Cron trigger that runs at 09:00 UTC every Monday.

Add error notifications. Burnrate or Windsurf might fail or return unexpected data. Add an error handling path in n8n that sends a Slack message if any step fails. Use a Slack node and configure it to send to your #engineering channel with details about which step failed.

Implement incremental scans for large codebases. If you have thousands of files, a single Burnrate scan might time out. Break the repository into chunks by directory and run parallel scans. Create separate workflow branches in n8n for src/api, src/ui, src/utils, etc., then merge the results before passing to Windsurf.

Cache Windsurf responses if you scan frequently. Language model API calls are slower and more expensive than static analysis. If you're running weekly scans, store the previous migration plan and only send Windsurf the delta (new issues, resolved issues) rather than the complete report each time. This cuts API costs by 60-80% and response time by half.

Set up version control for documentation. Commit each generated migration report to a docs/ branch in your repository so you have a historical record. This lets you track how technical debt changes over time and measure improvement. Mintlify supports versioned documentation, so readers can see migration plans from previous quarters.

Cost Breakdown

If you're a small team doing this quarterly instead of weekly, you can drop to Windsurf's Starter plan (£10/month) and use n8n's free tier (manual triggers only), bringing total cost to around £290/month. For very large codebases requiring more Windsurf tokens, upgrade to the Enterprise plan at £100/month.

The real cost savings come from not having a developer spend 4-6 hours per week manually analysing code and writing migration documentation. At a typical developer rate of £60/hour, you're saving £15,000-20,000 per quarter while getting more frequent, more accurate assessments.