diff --git a/src/fiona/data/llm_wiki/utils/skills/specification-writer/SKILL.md b/src/fiona/data/llm_wiki/utils/skills/specification-writer/SKILL.md index e518ae9..6181426 100644 --- a/src/fiona/data/llm_wiki/utils/skills/specification-writer/SKILL.md +++ b/src/fiona/data/llm_wiki/utils/skills/specification-writer/SKILL.md @@ -1,6 +1,7 @@ --- name: specification-writer -description: Load this skill when writing or updating project specifications (SPEC.md). Expert in creating structured, comprehensive, and maintainable specification documents for software projects. +description: Load when writing or updating project specifications (SPEC.md). + Expert in creating structured and maintainable specification documents. type: skill version: 1.0.0 created: 2026-11-03 @@ -9,11 +10,15 @@ updated: 2026-11-03 # Specification Writer -You are an expert in writing software project specifications. This skill provides guidance on creating structured, comprehensive, and maintainable SPEC.md files following best practices established by fiona-assistant and agent-cost-estimator projects. +You are an expert in writing software project specifications. +This skill provides guidance on creating structured, comprehensive, and +maintainable SPEC.md files following best practices established by +fiona-assistant and agent-cost-estimator projects. ## When to Load Load this skill when: + - Creating a new SPEC.md file for a project - Updating or expanding an existing specification - Reviewing specification structure and content @@ -21,13 +26,17 @@ Load this skill when: ## Core Principles -**Always apply sectionize-markdown conventions** to every SPEC.md file. Reference: [sectionize-markdown skill](../sectionize-markdown/SKILL.md) +### Sectionize-Markdown Conventions -- **Every heading MUST be numbered**: `## 1.` for sections, `### 1.1` for subsections, etc. -- **Every list item MUST have a bold ID**: `- **1.1.1** Text` -- **TOC MUST be present** under the title with markdown links -- **Anchors MUST follow GitHub-style slugs** -- **Never renumber existing IDs** - they may be cited elsewhere +Always apply sectionize-markdown conventions to every SPEC.md file. +Reference: [sectionize-markdown skill](../sectionize-markdown/SKILL.md) + +- Every heading MUST be numbered: `## 1.` for sections, `### 1.1` + for subsections, etc. +- Every list item MUST have a bold ID: `- **1.1.1** Text` +- TOC MUST be present under the title with markdown links +- Anchors MUST follow GitHub-style slugs +- Never renumber existing IDs - they may be cited elsewhere ## SPEC.md Structure Template @@ -63,101 +72,103 @@ updated: -This document is the build contract for . A reader with -this file, and no source tree, must be able to produce the same -observable software. Status values are `Implemented`, `Partially -Implemented`, `Planned`, and `Not Implemented`. +This document is the build contract for . +A reader with this file, and no source tree, must be able to produce +the same observable software. +Status values are `Implemented`, `Partially Implemented`, `Planned`, +and `Not Implemented`. --- +``` -## 1. Product Overview +## Product Overview -### 1.1. Purpose +### Purpose - **1.1.1** Clearly state what problem the project solves - **1.1.2** Describe the primary value proposition - **1.1.3** Identify the target users/audience -### 1.2. Scope +### Scope - **1.2.1** **In Scope**: List what the project will do - **1.2.2** **Out of Scope**: List what the project will NOT do -### 1.3. Non-Goals +### Non-Goals - **1.3.1** Explicitly state what will not be implemented - **1.3.2** Clarify boundaries with related projects -### 1.4. Document Conventions +### Document Conventions - **1.4.1** Define terminology used throughout - **1.4.2** Establish status labels (Implemented, Planned, etc.) - **1.4.3** Specify numbering conventions - **1.4.4** Define RFC2119 keywords (MUST, SHALL, SHOULD, MAY) -## 2. Architecture +## Architecture -### 2.1. Component Diagram +### Component Diagram - **2.1.1** Provide ASCII or Mermaid diagram - **2.1.2** Label all major components - **2.1.3** Show data flow between components -### 2.2. Data Flow +### Data Flow - **2.2.1** Describe how data moves through the system - **2.2.2** Identify key transformations - **2.2.3** Note persistence points -### 2.3. Module Structure +### Module Structure - **2.3.1** Document the directory structure - **2.3.2** Describe each module's responsibility - **2.3.3** Note cross-module dependencies -## 3. Core Contracts +## Core Contracts Define the fundamental interfaces and data structures: -### 3.1. Interface +### Interface Definition - **3.1.1** Purpose of the interface - **3.1.2** Required methods/functions - **3.1.3** Expected inputs and outputs - **3.1.4** Error handling expectations -### 3.2. Format +### Data Structure Format - **3.2.1** JSON Schema or type definitions - **3.2.2** Example instances - **3.2.3** Validation rules - **3.2.4** Version compatibility notes -## 4. Package and Runtime +## Package and Runtime -### 4.1. Dependencies +### Dependencies - **4.1.1** Runtime dependencies with versions - **4.1.2** Development dependencies - **4.1.3** Optional dependencies -### 4.2. Entry Points +### Entry Points - **4.2.1** CLI entry points - **4.2.2** Library entry points - **4.2.3** Plugin/extension entry points -### 4.3. Installation +### Installation - **4.3.1** Installation methods (pip, source, etc.) - **4.3.2** Platform requirements - **4.3.3** Verification steps -## 5. Feature Requirements +## Feature Requirements Organize by major feature areas: -### 5.X. +### Feature Template - **5.X.1** Status: Implemented/Planned/Not Implemented - **5.X.2** Purpose and user stories @@ -165,9 +176,9 @@ Organize by major feature areas: - **5.X.4** Non-functional requirements - **5.X.5** Acceptance criteria -## 6. Configuration Files +## Configuration Files -### 6.1. +### Configuration File Template - **6.1.1** Location (relative and absolute paths) - **6.1.2** Purpose @@ -175,49 +186,49 @@ Organize by major feature areas: - **6.1.4** Default values - **6.1.5** Customization options -## 7. Error Handling +## Error Handling -### 7.1. Error Classification +### Error Classification - **7.1.1** Transient vs permanent errors - **7.1.2** Recoverable vs unrecoverable errors - **7.1.3** User-facing vs internal errors -### 7.2. Error Reporting +### Error Reporting - **7.2.1** Logging strategy - **7.2.2** User notifications - **7.2.3** Error codes and messages -### 7.3. Recovery Strategies +### Recovery Strategies - **7.3.1** Automatic recovery mechanisms - **7.3.2** Manual recovery procedures - **7.3.3** Data consistency guarantees -## 8. Testing +## Testing -### 8.1. Test Strategy +### Test Strategy - **8.1.1** Testing pyramid (unit, integration, system) - **8.1.2** Test coverage targets - **8.1.3** Test environments -### 8.2. Test Cases +### Test Cases - **8.2.1** Critical path tests - **8.2.2** Edge case tests - **8.2.3** Regression tests -## 9. Deployment +## Deployment -### 9.1. Release Process +### Release Process - **9.1.1** Versioning scheme - **9.1.2** Release checklist - **9.1.3** Rollback procedures -### 9.2. Distribution +### Distribution - **9.2.1** Package repositories - **9.2.2** Installation methods @@ -226,19 +237,24 @@ Organize by major feature areas: ## Best Practices from Reference Projects Study these existing SPEC.md files for patterns: + - [Fiona-Assistant SPEC.md](https://gitea.nolivaldeziii.com/nvaldeziii/fiona-assistant/src/branch/master/SPEC.md) - [Agent Cost Estimator SPEC.md](https://gitea.nolivaldeziii.com/nvaldeziii/agent-cost-estimator/src/branch/master/SPEC.md) ### Patterns to Emulate -- **Fiona-Assistant**: Comprehensive violation rule catalog, clear status tracking -- **Agent Cost Estimator**: Modular harness adapter documentation, detailed integration steps +- **Fiona-Assistant**: Comprehensive violation rule catalog, + clear status tracking +- **Agent Cost Estimator**: Modular harness adapter documentation, + detailed integration steps ## Sectionize-Markdown Integration -**CRITICAL**: Every SPEC.md file you create or modify MUST follow sectionize-markdown conventions. +**CRITICAL**: Every SPEC.md file you create or modify MUST follow +sectionize-markdown conventions. Before finalizing any SPEC.md: + 1. Apply numbered headings (## 1., ### 1.1, #### 1.1.1) 2. Add bold IDs to all list items (- **1.1.1**) 3. Generate/update the TOC with markdown links @@ -271,6 +287,7 @@ Before marking a SPEC as complete: ## Tools and Automation When working with SPEC files: + - Use scripts to verify section numbering - Automate TOC generation - Validate all internal links