RFC Process: How we plan complex features before code

[santifer]

Why RFCs?

career-ops is growing fast. We get PRs that touch 5 files and PRs that touch 60. Both are welcome — but they need different processes.

For small changes (bug fixes, docs, translations): open an issue, submit a PR. Done.

For complex features (new modes, new integrations, architectural changes): we're introducing an RFC (Request for Comments) step. Plan first, then code.

When do you need an RFC?

If your feature will:

• Touch more than 5 files
• Add a new mode or integration
• Modify DATA_CONTRACT.md, CLAUDE.md, or _shared.md
• Introduce new dependencies
• Require multiple PRs to complete

What goes in an RFC?

Post a Discussion in this category with:

1. Problem — What user need does this solve?
2. Proposed solution — High-level approach, not code
3. Files affected — Which system/user files will change?
4. Data Contract impact — Any new files? How are they classified (user vs system)?
5. Phases — How would you break this into mergeable PRs?
6. Open questions — What needs community input?

The flow

Idea → RFC Discussion (community feedback) → Approved → PRs by phase → Merge

Why this matters

This was inspired by @minwoo-data's work on the visa module (PR #200). They came with a fully planned implementation: research phases, security review, validation criteria, and correct Data Contract handling. That's exactly the level of thinking we want for complex features — we just needed a place for it.

Top-tier projects like Kubernetes (KEPs), Rust (RFCs), and React (RFCs) all use this pattern. Now career-ops does too.

Existing umbrella issues

These track ongoing multi-PR efforts:

• #272 — Multi-CLI & AI-Agnostic Support
• #230 — Scanner & Job Board Providers

If your RFC fits under one of these, reference it.

Let's build together.