Platonic Implementation Guide

Create concrete, project-specific implementation designs from RFC specifications.

When to Use This Skill

Use this skill when you need to:

• Translate RFC specifications into implementation-ready designs
• Create detailed technical architecture for a feature
• Document language-specific and framework-specific implementation decisions
• Plan module structure, dependencies, and data flow
• Bridge the gap between abstract specs and concrete code

Keywords: implementation guide, technical design, architecture, RFC implementation, module design

What This Skill Does

This skill creates Implementation Guides that:

✅ Supersede RFC Specs: Provide concrete details while NEVER contradicting specs
✅ Language-Aware: Include language-specific idioms, patterns, and best practices
✅ Framework-Aware: Leverage framework capabilities and conventions
✅ Project-Specific: Align with existing codebase architecture and patterns
✅ Actionable: Provide clear module structure, types, and interfaces

Core Principles

1. Spec Compliance (Non-Negotiable)

Implementation guides MUST NOT contradict RFC specifications:

• All invariants from specs must be preserved
• All required behaviors must be implemented
• All constraints must be respected
• If a spec is unclear, document the interpretation

2. Concrete Over Abstract

Unlike RFCs which define “what”, implementation guides define “how”:

• Specific module/crate/package structure
• Concrete type definitions with fields
• Actual function signatures
• Real dependency relationships
• Specific storage formats and schemas

3. Language and Framework Awareness

Implementation guides are technology-specific:

• Use idiomatic patterns for the target language
• Leverage framework conventions and capabilities
• Follow project-established coding standards
• Reference actual libraries and dependencies

4. Traceability

Every implementation decision should trace back to specs:

• Reference source RFCs explicitly
• Document which spec requirements each component satisfies
• Explain deviations or interpretations

Implementation Guide Structure

An implementation guide follows this structure:

# [Feature] Implementation Architecture

> Implementation guide for [feature] in [project].
> 
> **Crate/Module**: `module-name`
> **Source**: Derived from RFC-NNNN (Title)
> **Related RFCs**: RFC-XXXX, RFC-YYYY

---

## 1. Overview
[High-level summary of what this implements and why]

## 2. Architectural Position
[Where this fits in the overall system]
- Data flow diagram
- Dependency graph
- Crate/module responsibilities

## 3. Module Structure
[Concrete directory and file layout]

## 4. Core Types
[Actual type definitions with fields and documentation]

## 5. Key Interfaces/Traits
[API surface with function signatures]

## 6. Implementation Details
[Specific algorithms, storage formats, protocols]

## 7. Error Handling
[Error types and handling strategies]

## 8. Configuration
[Configuration options and defaults]

## 9. Testing Strategy
[How to test this implementation]

## 10. Migration/Compatibility
[If applicable, how to migrate from existing systems]

Available Operations

See references/REFERENCE.md for detailed operation guides.

Templates

Templates are provided in assets/:

• impl-guide-template.md – Full implementation guide template

Usage Examples

Example 1: Create Implementation Guide

Use platonic-impl-guide to create an implementation guide for 
RFC-0042 (Message Queue Protocol) targeting the acme-queue crate.
The implementation should use Rust with async/await patterns.

Example 2: Validate Existing Guide

Use platonic-impl-guide to validate that references/queue_impl.md
does not contradict RFC-0042 specifications.

Example 3: Update Guide After RFC Change

Use platonic-impl-guide to update the implementation guide
after RFC-0042 was revised to add new message priority levels.

Best Practices

1. Read the RFC first: Understand the specification completely before designing implementation
2. Check existing patterns: Look at how similar features are implemented in the project
3. Document decisions: Explain why specific implementation choices were made
4. Keep it current: Update guides when RFCs or implementations change
5. Be specific: Vague guides are not useful; include actual types and signatures
6. Test coverage: Include testing strategy in the guide

Relationship to Other Artifacts

RFC Specification (abstract, what)
        ↓
Implementation Guide (concrete, how)  ← This skill
        ↓
Actual Code (executable)
        ↓
Tests (verification)

Dependencies

• Read access to RFC specifications
• Understanding of target language and framework
• Knowledge of project architecture and conventions
• Write access to references/ or designated impl-guide directory