mgiovani/docs-rfc

Docs Rfc

Cross-Platform AI Agent Skill This skill works with any AI agent platform that supports the skills.sh standard.

Create Request For Comments

Create a new RFC (Request For Comments) document for proposing and discussing changes.

Anti-Hallucination Guidelines

CRITICAL: RFCs propose changes to REAL systems. Before writing:

1. Verify current state - Explore the codebase to understand what exists today
2. Reference actual code - Do not invent APIs or patterns; find real examples
3. Check dependencies - Verify libraries/tools mentioned actually exist in project
4. Validate assumptions - Each claim about current state must be verified

Workflow

Phase 1: Explore Current State (Explore Codebase)

Before writing an RFC, thoroughly explore the codebase to understand current state:

Phase 2: Parse Arguments

1. Extract proposal title from command arguments
2. Check for variant keyword: minimal, standard, or detailed
3. If variant found, remove it from title
4. Default variant: standard

Phase 3: Determine RFC Number

• Scan docs/rfc/ directory
• Find highest existing RFC number (format: RFC-XXXX-*)
• Increment by 1
• If no RFCs exist, start with 0001
• Format as 4-digit padded number (e.g., 0001, 0023)

Phase 4: Sanitize Title for Filename

• Convert title to kebab-case
• Remove special characters
• Lowercase all letters
• Example: "Add GraphQL API Support" -> add-graphql-api-support

Phase 5: Gather Context

• Analyze codebase to understand current state
• Identify relevant files and patterns
• Find similar implementations or related features
• Understand technical constraints

Phase 6: Get Author Information

# Try to get git author
!`git config user.name 2>/dev/null || echo "Development Team"`
### Phase 7: Load and Populate Template

- Template location: `assets/templates/`
- Select based on variant:
 - `minimal` -> `minimal.md`
 - `standard` -> `standard.md` (default)
 - `detailed` -> `detailed.md`

Replace placeholders:
- `{{RFC_NUMBER}}` - 4-digit number
- `{{RFC_TITLE}}` - Original title (Title Case)
- `{{DATE}}` - Current date (YYYY-MM-DD)
- `{{AUTHOR}}` - Git user name or "Development Team"
- `{{CONTEXT}}` - Gathered context from codebase
- `{{PROJECT_NAME}}` - Git repo or directory name

### Phase 8: Create RFC File

- Filename: `docs/rfc/RFC-XXXX-kebab-case-title.md`
- Ensure `docs/rfc/` directory exists
- Write populated content
- Set initial status to "Draft"

### Phase 9: Report Creation

- Show RFC number and title
- Display file path
- Provide workflow guidance

## Template Variants

### Minimal Template
Quick proposal format for small changes.

**Sections:** Summary, Motivation, Proposal, Open Questions

**Use when:** Small features, minor changes

### Standard Template (Default)
Balanced RFC for most changes.

**Sections:** Summary, Motivation, Proposal, Rationale and Alternatives, Implementation Plan, Testing Plan, Migration Strategy, Open Questions, Timeline

**Use when:** Most feature proposals

### Detailed Template
Comprehensive RFC for major changes.

**Sections:** Summary, Background and Motivation, Goals and Non-Goals, Proposal, Detailed Design, Rationale and Alternatives, Implementation Plan, Testing and Quality Assurance, Migration and Rollout Strategy, Monitoring and Metrics, Security Considerations, Performance Implications, Open Questions and Risks, Timeline and Milestones, Appendices

**Use when:** Major features, architectural changes

## Usage Examples

Basic RFC creation (uses Standard template):

docs-rfc "Add GraphQL API Support" docs-rfc "Implement Rate Limiting" docs-rfc "Add Multi-Tenancy Support" With template variant override:

docs-rfc minimal "Update Logging Format"
docs-rfc detailed "Migration to Microservices Architecture"
docs-rfc detailed "Adopt Event Sourcing Pattern"
## RFC Status Lifecycle

Update status in the RFC as it progresses:

1. **Draft** - Initial proposal, gathering feedback
2. **In Review** - Under discussion, modifications being made
3. **Accepted** - Approved for implementation
4. **Implemented** - Changes have been deployed
5. **Rejected** - Not moving forward with proposal
6. **Withdrawn** - Author withdrew the proposal

## RFC Workflow

### 1. Create RFC

docs-rfc "Proposal Title"

2. Initial Draft

• Write comprehensive proposal
• Include motivation and context
• Document alternatives considered
• Add implementation plan

3. Share for Feedback

• Share RFC with team
• Update status to "In Review"
• Collect feedback in comments or discussions

4. Iterate

• Incorporate feedback
• Update proposal as needed
• Address concerns and questions
• Refine implementation details

5. Final Decision

• Stakeholders review final version
• Update status to "Accepted" or "Rejected"
• Document decision rationale

6. Implementation

• Reference RFC in PRs
• Update RFC with implementation notes
• Mark status as "Implemented" when complete

Context Gathering Examples

# For API changes
!`find . -name "*router*" -o -name "*controller*" -o -name "*api*" | head -10`

# For feature additions
!`grep -r "export.*function\|export.*class" --include="*.ts" --include="*.js" . | head -20`

# For infrastructure changes
!`find . -name "*.yml" -o -name "*.yaml" -o -name "Dockerfile" | head -10`

# For performance changes
!`grep -r "cache\|redis\|memcache\|performance" --include="*.py" --include="*.ts" . | head -15`
## Important Notes

- **Write Before Implementing**: Create RFCs before starting work
- **Concrete Examples**: Include real code examples when possible
- **Address Concerns**: Proactively address potential objections
- **Update Actively**: RFC is a living document during review
- **Link Related Work**: Reference ADRs, issues, or other RFCs
- **Clear Language**: Keep accessible to all stakeholders
- **Define Success**: Include measurable success criteria

## When to Create RFCs

Create an RFC when proposing:
- Major feature additions
- Significant refactorings
- Architecture changes
- Breaking API changes
- New technology adoptions
- Process changes
- Performance optimizations with trade-offs
- Security enhancements
- Developer experience improvements

## Best Practices

- **Early Documentation**: Write RFC before implementation
- **Be Specific**: Include concrete examples and details
- **Show Your Work**: Document research and investigation
- **Consider Alternatives**: Show what else was considered and why
- **Realistic Timeline**: Include reasonable milestones
- **Risk Assessment**: Document known risks and mitigation
- **Stakeholder Input**: Identify who should review
- **Clear Outcomes**: Define what success looks like
- **Keep Updated**: Reflect changes made during review

## Claude Code Enhanced Features

This skill includes the following Claude Code-specific enhancements:

## Workflow

### Phase 1: Explore Current State (Use Explore Agent)

Before writing an RFC, thoroughly explore the codebase to understand current state:

Use Task tool with Explore agent:

• prompt: "Analyze the codebase to understand [RFC_TOPIC]. Find: 1) Current implementation patterns, 2) Related components and their interactions, 3) Existing similar features, 4) Technical constraints. Return verified findings with file paths."
• subagent_type: "Explore"

### Phase 2: Parse Arguments

1. Extract proposal title from `$ARGUMENTS`
2. Check for variant keyword: `minimal`, `standard`, or `detailed`
3. If variant found, remove it from title
4. Default variant: `standard`

### Phase 3: Determine RFC Number

- Scan `docs/rfc/` directory
- Find highest existing RFC number (format: `RFC-XXXX-*`)
- Increment by 1
- If no RFCs exist, start with `0001`
- Format as 4-digit padded number (e.g., `0001`, `0023`)

### Phase 4: Sanitize Title for Filename

- Convert title to kebab-case
- Remove special characters
- Lowercase all letters
- Example: "Add GraphQL API Support" -> `add-graphql-api-support`

### Phase 5: Gather Context

- Analyze codebase to understand current state
- Identify relevant files and patterns
- Find similar implementations or related features
- Understand technical constraints

### Phase 6: Get Author Information

```bash
# Try to get git author
!`git config user.name 2>/dev/null || echo "Development Team"`

Phase 7: Load and Populate Template

• Template location: assets/templates/
• Select based on variant:
  • minimal -> minimal.md
  • standard -> standard.md (default)
  • detailed -> detailed.md

Replace placeholders:

• {{RFC_NUMBER}} - 4-digit number
• {{RFC_TITLE}} - Original title (Title Case)
• {{DATE}} - Current date (YYYY-MM-DD)
• {{AUTHOR}} - Git user name or "Development Team"
• {{CONTEXT}} - Gathered context from codebase
• {{PROJECT_NAME}} - Git repo or directory name

Phase 8: Create RFC File

• Filename: docs/rfc/RFC-XXXX-kebab-case-title.md
• Ensure docs/rfc/ directory exists
• Write populated content
• Set initial status to "Draft"

Phase 9: Report Creation

• Show RFC number and title
• Display file path
• Provide workflow guidance