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

Operation Reference File Purpose

Create Guide create-guide.md

Create new implementation guide from RFC

Validate Guide validate-guide.md

Check guide against RFC for contradictions

Update Guide update-guide.md

Update guide when RFC changes

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 docs/impl/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

• Read the RFC first: Understand the specification completely before designing implementation

• Check existing patterns: Look at how similar features are implemented in the project

• Document decisions: Explain why specific implementation choices were made

• Keep it current: Update guides when RFCs or implementations change

• Be specific: Vague guides are not useful; include actual types and signatures

• 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 docs/impl/ or designated impl-guide directory