Octocode RFC Generator

Use this skill when a change needs thinking before coding: architecture choices, migrations, cross-package changes, risky refactors, implementation plans, or formal RFC/design docs. The output is evidence-backed and actionable, not a brainstorm.

Core flow:

UNDERSTAND → RESEARCH → COMPARE OPTIONS → WRITE RFC / PLAN → VALIDATE → DELIVER

Default output location when saving is approved: .octocode/rfc/RFC-{meaningful-name}.md.

1. Pick mode

If the task is a trivial one-file edit with no design choice, say an RFC is unnecessary and suggest using octocode-engineer directly.

2. Research with Octocode

Pick MCP if available; otherwise use the CLI. Do not guess facts that tools can verify.

Local codebase evidence

Use when the current repo matters.

Local flow:

ls → find/grep → symbols → matchString/line range → AST/LSP → cited current-state evidence

External evidence

Use for prior art, package choices, cross-repo comparison, and history.

External flow:

pkg/repo → ghViewRepoStructure → ghSearchCode path/content discovery → ghGetFileContent proof → history/PR rationale

Clone and switch to local tools when analysis spans several files or needs AST/LSP.

Binary/archive evidence

Use when the source is packaged or compiled.

Flow: identify/list → extract one entry or unpack all → run local tools on the returned localPath.

3. Understand

Capture this before research gets broad:

• Problem in one or two sentences.
• Why this needs a decision/plan.
• Affected users, packages, APIs, teams, or workflows.
• Constraints: compatibility, performance, security, rollout, tech stack.
• What “do nothing” costs.
• What evidence is needed to decide.

Ask if the problem or desired output mode is unclear.

4. Research plan

Run only the tracks that matter.

Evidence rules:

• Local claims need file:line.
• External code claims need GitHub file path/line or PR/commit link.
• Snippets are leads; use matchString, line ranges, AST, LSP, or history before citing.
• Key recommendations need at least one supporting source and one counterpoint or rejected alternative.

5. Compare options

Always include at least two alternatives unless the user explicitly asks for a single implementation plan.

Useful alternatives:

• Do nothing / defer.
• Minimal patch.
• Incremental migration.
• Full redesign.
• Adopt package/library.
• Build in-house.
• Hybrid/phased rollout.

Compare on:

• Fit with current architecture.
• Blast radius.
• Compatibility and migration cost.
• Operational risk.
• Performance/security/data implications.
• Maintenance and ownership.
• Reversibility.

6. Write the RFC or plan

Use references/rfc-template.md for full RFCs; do not duplicate the whole template in the prompt. For implementation plans, include only the sections needed for the work:

# Plan: <title>

## Goal
## Evidence Summary
## Current State
## Proposed Approach
## Alternatives Considered
## Step-by-Step Implementation
## Files / APIs / Contracts Touched
## Test and Verification Plan
## Rollout / Migration / Rollback
## Risks and Open Questions

Implementation steps should be ordered by dependency, not preference. Avoid time estimates.

7. Validate

Before delivering, check:

• Problem and motivation are specific.
• Current state has real evidence.
• Alternatives are fairly compared.
• Recommendation follows from evidence.
• Drawbacks and migration costs are explicit.
• Blast radius is mapped for shared symbols/contracts.
• Risks have mitigations or open questions.
• Implementation plan is actionable and verifiable.
• No claim relies on “common practice” without explaining why it applies here.

Reasoning traps:

• First-option bias: search for evidence against the preferred approach.
• False dichotomy: consider hybrids/phased plans.
• Local-vs-external conflict: local constraints usually win; document the tradeoff.
• Metrics claims: use external tools or mark as approximation.

8. Deliver

Start with a concise summary:

Decision: <recommendation>
Why: <1-2 evidence-backed reasons>
Alternatives: <count and names>
Risk: <low|medium|high + why>
Next step: <one action>

Then ask whether to save the full RFC/plan.

• If yes: save to .octocode/rfc/RFC-{meaningful-name}.md.
• If no: keep it in chat.
• If user wants implementation: hand off to the agent’s normal engineering/edit workflow using the implementation plan.

9. Recovery