docs: add RFC writing and review guides

.kiro/steering/rfc-review-guide.md

@@ -0,0 +1,185 @@
+# RFC Review Guide
+
+This guide provides criteria and best practices for reviewing AWS CDK RFCs effectively.
+
+## Quality Indicators for Good RFCs
+
+### Essential Components
+
+**Working Backwards**: Comprehensive user experience documentation with concrete examples, README sections, and CHANGELOG entries. This should read like actual product documentation.
+
+**Technical Depth**: Detailed algorithms, edge cases, implementation specifics, and formal definitions. The RFC should provide enough detail to implement the feature.
+
+**API Design**: Clear interfaces, proper abstractions, inheritance hierarchies, and complete method signatures. APIs should follow CDK patterns and be extensible.
+
+**Implementation Planning**: Phased approach with concrete tasks, timelines, and migration strategies. The plan should be realistic and actionable.
+
+**Alternatives Analysis**: Thorough consideration of different approaches with trade-offs and rationale. Show that multiple solutions were explored.
+
+### Structure and Documentation
+
+**Clear Problem Statement**: Well-defined motivation, scope, and customer impact. Why does this feature matter?
+
+**Comprehensive Examples**: Multiple use cases with complete code samples in all supported languages. Examples should be realistic and runnable.
+
+**Migration Strategy**: For breaking changes, detailed upgrade paths and compatibility plans. How will existing users adopt this?
+
+**Security Considerations**: Proper handling of permissions, cross-account scenarios, and IAM policies. Security should not be an afterthought.
+
+**Extensibility**: Future-proofing, enhancement considerations, and backward compatibility. How will this evolve?
+
+## Red Flags for Poor RFCs
+
+**Brevity Without Substance**: Too short for the complexity of the feature (under 5 pages for complex features). Lack of detail indicates insufficient thinking.
+
+**Missing Working Backwards**: No user experience documentation or README sections. Without this, the RFC is just a technical spec.
+
+**Incomplete API Design**: Vague interfaces, missing method signatures, or unclear abstractions. APIs should be fully specified.
+
+**No Implementation Plan**: Lack of concrete next steps or phased approach. How will this actually get built?
+
+**Missing Alternatives**: No consideration of other approaches or design decisions. Was this the only option explored?
+
+**Unsigned API Bar Raiser**: Missing required sign-off from designated reviewer. Process compliance matters.
+
+## Review Checklist
+
+### Content Quality
+
+- [ ] Working backwards section with realistic examples and README content
+- [ ] Detailed technical implementation approach with algorithms and data structures
+- [ ] Comprehensive API documentation with complete type definitions
+- [ ] Implementation plan with phases, tasks, and concrete deliverables
+- [ ] Analysis of alternatives with clear trade-offs and decision rationale
+- [ ] Security, compatibility, and performance considerations addressed
+
+### Process Compliance
+
+- [ ] API Bar Raiser assigned and signed off (status/api-approved label)
+- [ ] Proper RFC template structure followed with all sections
+- [ ] All required sections completed (not just placeholders)
+- [ ] Tracking issue properly linked and maintained
+- [ ] Appropriate labels applied throughout lifecycle
+
+### Technical Review
+
+- [ ] API design follows CDK patterns and conventions
+- [ ] Breaking changes properly handled with migration paths
+- [ ] Edge cases, error scenarios, and failure modes addressed
+- [ ] Performance, scalability, and resource usage considerations
+- [ ] Integration with existing CDK features and constructs
+
+## Review Process
+
+### Before Reviewing
+
+1. Check if RFC has API Bar Raiser sign-off requirement
+2. Verify RFC follows the template structure
+3. Ensure tracking issue is properly linked
+
+### During Review
+
+**Completeness Check**: All required sections present, working backwards artifacts included, technical solution documented, implementation plan provided.
+
+**Quality Assessment**: Technical depth appropriate for complexity, examples are practical and realistic, API design is consistent and extensible, error handling and edge cases considered.
+
+**Feasibility Review**: Implementation approach is realistic, dependencies and prerequisites identified, timeline and resource requirements reasonable, breaking change impact assessed.
+
+### Questions to Ask
+
+1. Does this RFC solve a real customer problem?
+2. Is the proposed API intuitive and consistent with CDK patterns?
+3. Are the examples realistic and comprehensive?
+4. Is the implementation approach feasible and well-planned?
+5. Have alternatives been properly considered?
+6. Are breaking changes properly justified and documented?
+7. Is the technical depth appropriate for the feature complexity?
+
+## Review Feedback Guidelines
+
+### Constructive Feedback
+
+- Ask for specific examples when concepts are unclear or abstract
+- Request detailed implementation for complex features and algorithms
+- Suggest alternative approaches with clear reasoning and trade-offs
+- Point out missing edge cases, error scenarios, or failure modes
+- Recommend improvements to API ergonomics and developer experience
+
+### What to Look For
+
+**In Working Backwards**: Does it read like real documentation? Are examples complete and realistic? Would a customer understand how to use this?
+
+**In Technical Design**: Is there enough detail to implement? Are edge cases covered? Are algorithms and data structures specified?
+
+**In API Design**: Is it consistent with CDK patterns? Is it extensible? Are all methods and properties documented?
+
+**In Implementation Plan**: Is it realistic? Are phases clearly defined? Are dependencies identified?
+
+**In Alternatives**: Were multiple approaches considered? Is the rationale clear? Are trade-offs honestly assessed?
+
+## Approval Criteria
+
+### Must Have
+
+- Complete working backwards documentation
+- Comprehensive technical solution
+- Realistic implementation plan
+- API Bar Raiser sign-off (if required)
+- Proper consideration of alternatives
+
+### Should Have
+
+- Multiple practical examples
+- Detailed API documentation
+- Error handling strategy
+- Migration/compatibility plan
+- Performance considerations
+
+### Nice to Have
+
+- Formal mathematical definitions
+- Comprehensive appendices
+- Advanced use case coverage
+- Integration with other services
+
+## Common Issues and Solutions
+
+**Issue: Incomplete Working Backwards**
+Solution: Request comprehensive README with multiple examples and use cases
+
+**Issue: Insufficient Technical Depth**
+Solution: Ask for detailed implementation approach, algorithms, and edge case handling
+
+**Issue: Poor API Design**
+Solution: Review for consistency, extensibility, and CDK patterns compliance
+
+**Issue: Missing Implementation Plan**
+Solution: Require phased approach with concrete tasks and timelines
+
+**Issue: No Alternative Analysis**
+Solution: Request comparison of different approaches with trade-offs
+
+## Examples to Study
+
+### Excellent RFCs
+
+- **RFC 162 (Refactoring Support)**: Exceptional technical depth with formal definitions
+- **RFC 49 (Continuous Delivery)**: Comprehensive end-to-end solution with security model
+- **RFC 431 (SageMaker L2)**: Excellent API design with clear abstractions
+- **RFC 340 (Firehose L2)**: Comprehensive feature coverage with thorough alternatives
+
+### Poor RFCs to Avoid
+
+- **RFC 95 (Cognito)**: Extremely brief, no working backwards, missing technical details
+- **RFC 359 (Construct Hub Deny List)**: Very short, lacks comprehensive coverage
+- **RFC 670/673 (Application Signals)**: Incomplete, not signed off, limited examples
+
+## Final Recommendations
+
+1. **Be Thorough**: Don't approve RFCs that lack essential details
+2. **Focus on User Experience**: Ensure working backwards truly represents customer value
+3. **Demand Quality**: High-impact features require high-quality documentation
+4. **Consider Maintainability**: Evaluate long-term support and evolution
+5. **Validate Feasibility**: Ensure implementation approach is realistic and well-planned
+6. **Check Process**: Verify API Bar Raiser sign-off and proper labels
+7. **Think Long-term**: Consider how this will evolve and integrate with future features

.kiro/steering/rfc-writing-guide.md

@@ -0,0 +1,159 @@
+# RFC Writing Guide
+
+This guide provides best practices for writing high-quality AWS CDK RFCs based on analysis of successful and unsuccessful RFCs.
+
+## Start with Working Backwards
+
+The working backwards section is the most important part of your RFC. It should read like documentation for a feature that already exists.
+
+**Write the README first**: Create comprehensive user documentation as if the feature is already shipped. Include installation instructions, basic usage, advanced scenarios, and API reference.
+
+**Include CHANGELOG entries**: Write the release notes customers will see. Use conventional commit format: `feat(service): add L2 constructs for ServiceName`
+
+**Provide complete examples**: Show realistic usage patterns with full, runnable code samples. Cover simple to complex scenarios.
+
+**Cover all languages**: Include examples for TypeScript, Python, Java, C#, and Go where applicable.
+
+## Technical Design Requirements
+
+Provide comprehensive technical depth appropriate to the feature complexity.
+
+**Deep technical detail**: Include algorithms, data structures, implementation specifics, and architectural patterns. Don't be vague.
+
+**Edge case analysis**: Consider failure modes, error scenarios, boundary conditions, and how the system behaves under stress.
+
+**Formal definitions**: Use mathematical notation, pseudocode, or state diagrams where appropriate to clarify complex behavior.
+
+**Architecture diagrams**: Visual representations of complex systems, component interactions, and data flows.
+
+## API Design Excellence
+
+**Complete interfaces**: Define all methods, properties, type signatures, and return types. Show the full contract.
+
+**Inheritance hierarchies**: Clearly show class relationships, abstractions, and how components compose together.
+
+**Consistent patterns**: Follow existing CDK conventions, naming schemes, and design patterns. Don't invent new patterns without justification.
+
+**Extensibility**: Design for future enhancements and backward compatibility. Consider how users will extend your constructs.
+
+## Implementation Planning
+
+**Phased approach**: Break large features into manageable, deliverable phases with clear milestones.
+
+**Concrete tasks**: List specific implementation steps with owners, timelines, and dependencies.
+
+**Migration strategy**: For breaking changes, provide detailed upgrade paths and compatibility plans.
+
+**Testing strategy**: Define unit tests, integration tests, and how the feature will be validated.
+
+## Alternatives and Trade-offs
+
+**Multiple approaches**: Consider at least 2-3 different design alternatives. Show you've explored the solution space.
+
+**Clear rationale**: Explain why the chosen approach is superior with specific reasoning.
+
+**Trade-off analysis**: Document pros and cons of each alternative honestly.
+
+**Future considerations**: Note what options remain open for later enhancements.
+
+## Common Pitfalls to Avoid
+
+### Content Issues
+
+- **Too brief**: RFCs under 5 pages for complex features lack necessary detail
+- **Missing examples**: Abstract descriptions without concrete usage patterns
+- **Incomplete APIs**: Vague method signatures or missing type definitions
+- **No error handling**: Ignoring failure scenarios and edge cases
+- **Vendor-in dependencies**: Copying code instead of proper dependency management
+
+### Process Issues
+
+- **Skipping API Bar Raiser**: Not getting required sign-off before implementation
+- **Incomplete templates**: Leaving sections as placeholders or "TBD"
+- **Missing tracking**: Not linking to GitHub issues or maintaining status
+- **Poor formatting**: Inconsistent markdown, broken links, or unclear structure
+
+### Technical Issues
+
+- **Breaking CDK patterns**: Inconsistent with existing construct library conventions
+- **Security oversights**: Missing IAM considerations or cross-account scenarios
+- **Performance blindness**: Not considering scalability or resource usage
+- **Integration gaps**: Failing to consider interaction with existing features
+
+## RFC Structure Template
+
+### 1. Summary and Motivation
+
+- Clear problem statement with customer impact
+- Scope definition and success criteria
+- Background context and current limitations
+
+### 2. Working Backwards
+
+- Complete README documentation
+- CHANGELOG entries
+- User experience walkthrough
+- Code examples in multiple languages
+
+### 3. Technical Design
+
+- Architecture overview with diagrams
+- Detailed implementation approach
+- Data structures and algorithms
+- Error handling and edge cases
+
+### 4. API Design
+
+- Complete interface definitions
+- Method signatures and type information
+- Usage patterns and examples
+- Backward compatibility considerations
+
+### 5. Implementation Plan
+
+- Phased delivery approach
+- Concrete tasks and milestones
+- Testing and validation strategy
+- Migration and rollout plan
+
+### 6. Alternatives Considered
+
+- Multiple design approaches
+- Trade-off analysis
+- Rationale for chosen solution
+- Future enhancement possibilities
+
+## Quality Checklist
+
+Before submitting your RFC:
+
+- [ ] Working backwards section reads like actual user documentation
+- [ ] Technical design includes sufficient detail for implementation
+- [ ] API design follows CDK patterns and conventions
+- [ ] Implementation plan is concrete and realistic
+- [ ] Alternatives analysis shows thorough consideration
+- [ ] All code examples are complete and functional
+- [ ] Security and performance implications addressed
+- [ ] Migration strategy provided for breaking changes
+- [ ] API Bar Raiser identified and engaged
+- [ ] All template sections completed (no placeholders)
+
+## Examples of Excellence
+
+Study these high-quality RFCs for inspiration:
+
+- **RFC 162 (Refactoring Support)**: Exceptional technical depth with formal definitions and comprehensive appendices
+- **RFC 49 (Continuous Delivery)**: Complete end-to-end solution with security model and migration strategy
+- **RFC 431 (SageMaker L2)**: Excellent API design with clear abstractions and future extensibility
+- **RFC 340 (Firehose L2)**: Comprehensive feature coverage with multiple destinations and thorough alternatives analysis
+
+## Final Tips
+
+1. **Start with the User**: Always begin with the working backwards section
+2. **Be Comprehensive**: Better to over-document than under-document
+3. **Use Real Examples**: Provide practical, runnable code samples
+4. **Plan Implementation**: Think through how you'll actually build this
+5. **Consider Alternatives**: Show you've thought about different approaches
+6. **Get Feedback Early**: Share drafts with colleagues before formal review
+7. **Iterate**: Be prepared to revise based on feedback
+8. **Focus on Quality**: High-impact features deserve high-quality RFCs