From def3d2cd6d188efdff5c531e3deca0dbf602079e Mon Sep 17 00:00:00 2001 From: nvaldez Date: Tue, 3 Nov 2026 16:34:25 +0100 Subject: [PATCH] Rewrite specification-writer skill to be self-contained - Remove references to fiona-assistant and agent-cost-estimator - Include all SPEC structure details directly in the skill - Add comprehensive section guidelines with numbered items - Expand core contracts, configuration files, error handling sections - Maintain sectionize-markdown integration - All housekeeping checks pass Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- .../skills/specification-writer/SKILL.md | 278 ++++++++++-------- 1 file changed, 148 insertions(+), 130 deletions(-) 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 6181426..e891f49 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 @@ -12,8 +12,7 @@ updated: 2026-11-03 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. +maintainable SPEC.md files following established best practices. ## When to Load @@ -62,8 +61,16 @@ updated: - [1.3. Non-Goals](#13-non-goals) - [1.4. Document Conventions](#14-document-conventions) - [2. Architecture](#2-architecture) + - [2.1. Component Diagram](#21-component-diagram) + - [2.2. Data Flow](#22-data-flow) + - [2.3. Module Structure](#23-module-structure) - [3. Core Contracts](#3-core-contracts) + - [3.1. Interfaces](#31-interfaces) + - [3.2. Data Structures](#32-data-structures) - [4. Package and Runtime](#4-package-and-runtime) + - [4.1. Dependencies](#41-dependencies) + - [4.2. Entry Points](#42-entry-points) + - [4.3. Installation](#43-installation) - [5. Feature Requirements](#5-feature-requirements) - [6. Configuration Files](#6-configuration-files) - [7. Error Handling](#7-error-handling) @@ -81,223 +88,234 @@ and `Not Implemented`. --- ``` -## Product Overview +## Detailed Section Guidelines -### Purpose +### 1. Product Overview + +#### 1.1. 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.1.3** Identify the target users or audience +- **1.1.4** Define the project's mission statement -### Scope +#### 1.2. 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.2.3** Define clear boundaries for the project -### Non-Goals +#### 1.3. Non-Goals - **1.3.1** Explicitly state what will not be implemented -- **1.3.2** Clarify boundaries with related projects +- **1.3.2** Clarify boundaries with related projects or systems +- **1.3.3** Document conscious exclusions and rationale -### Document Conventions +#### 1.4. 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) +- **1.4.1** Define terminology used throughout the document +- **1.4.2** Establish status labels and their meanings + - Implemented: Feature is complete and tested + - Partially Implemented: Feature is partially complete + - Planned: Feature is scheduled for implementation + - Not Implemented: Feature is specified but not yet built +- **1.4.3** Specify numbering conventions for sections and items +- **1.4.4** Define RFC2119 keywords (MUST, SHALL, SHOULD, MAY, etc.) -## Architecture +### 2. Architecture -### Component Diagram +#### 2.1. 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.1.1** Provide ASCII or Mermaid diagram showing system architecture +- **2.1.2** Label all major components and their relationships +- **2.1.3** Show data flow between components with arrows or descriptions +- **2.1.4** Indicate external dependencies and integrations -### Data Flow +#### 2.2. 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.2.1** Describe how data moves through the system end-to-end +- **2.2.2** Identify key data transformations at each stage +- **2.2.3** Note where data is persisted and in what format +- **2.2.4** Document data validation and error handling points -### Module Structure +#### 2.3. Module Structure -- **2.3.1** Document the directory structure -- **2.3.2** Describe each module's responsibility -- **2.3.3** Note cross-module dependencies +- **2.3.1** Document the complete directory and file structure +- **2.3.2** Describe each module's responsibility and purpose +- **2.3.3** Note dependencies between modules +- **2.3.4** Indicate which modules are public vs internal APIs -## Core Contracts +### 3. Core Contracts -Define the fundamental interfaces and data structures: +#### 3.1. Interfaces -### Interface Definition +- **3.1.1** Define purpose and role of each interface +- **3.1.2** List all required methods or functions with signatures +- **3.1.3** Document expected inputs, outputs, and return types +- **3.1.4** Specify error handling expectations and exceptions +- **3.1.5** Note version compatibility requirements -- **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. Data Structures -### Data Structure Format +- **3.2.1** Provide complete type definitions or JSON schemas +- **3.2.2** Include concrete examples of each data structure +- **3.2.3** Document validation rules and constraints +- **3.2.4** Note backward and forward compatibility considerations +- **3.2.5** Specify serialization formats (JSON, YAML, etc.) -- **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** List runtime dependencies with exact version requirements +- **4.1.2** List development dependencies for building and testing +- **4.1.3** Document optional dependencies and their purposes +- **4.1.4** Note any version conflicts or compatibility constraints -- **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** Define CLI entry points and their usage +- **4.2.2** Document library entry points for programmatic use +- **4.2.3** Specify plugin or extension entry points if applicable +- **4.2.4** Include examples of invoking each entry point -- **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** Document all supported installation methods +- **4.3.2** Specify platform and environment requirements +- **4.3.3** Provide verification steps to confirm successful installation +- **4.3.4** Note any post-installation configuration needed -- **4.3.1** Installation methods (pip, source, etc.) -- **4.3.2** Platform requirements -- **4.3.3** Verification steps +### 5. Feature Requirements -## Feature Requirements +Organize requirements by feature area. Each feature section should include: -Organize by major feature areas: +- **5.X.1** Status: One of Implemented, Partially Implemented, Planned, + Not Implemented +- **5.X.2** Purpose: User stories and motivations for the feature +- **5.X.3** Functional requirements: What the feature must do +- **5.X.4** Non-functional requirements: Performance, security, etc. +- **5.X.5** Acceptance criteria: How to verify the feature works -### Feature Template +### 6. Configuration Files -- **5.X.1** Status: Implemented/Planned/Not Implemented -- **5.X.2** Purpose and user stories -- **5.X.3** Functional requirements -- **5.X.4** Non-functional requirements -- **5.X.5** Acceptance criteria +For each configuration file, document: -## Configuration Files +- **6.1.1** Location: Both relative path and typical absolute paths + - Note platform-specific locations (Windows vs Unix) +- **6.1.2** Purpose: What the configuration controls +- **6.1.3** Structure: Complete format and schema +- **6.1.4** Default values: What settings are used if not specified +- **6.1.5** Customization: How users can modify the configuration -### Configuration File Template +### 7. Error Handling -- **6.1.1** Location (relative and absolute paths) -- **6.1.2** Purpose -- **6.1.3** Structure/format -- **6.1.4** Default values -- **6.1.5** Customization options - -## Error Handling - -### Error Classification +#### 7.1. 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.1.4** Expected vs unexpected errors -### Error Reporting +#### 7.2. Error Reporting -- **7.2.1** Logging strategy -- **7.2.2** User notifications -- **7.2.3** Error codes and messages +- **7.2.1** Logging strategy and verbosity levels +- **7.2.2** User notification mechanisms (CLI, UI, etc.) +- **7.2.3** Error codes and their meanings +- **7.2.4** Error message format and content -### Recovery Strategies +#### 7.3. Recovery Strategies -- **7.3.1** Automatic recovery mechanisms -- **7.3.2** Manual recovery procedures -- **7.3.3** Data consistency guarantees +- **7.3.1** Automatic recovery mechanisms and retries +- **7.3.2** Manual recovery procedures and user actions +- **7.3.3** Data consistency guarantees during failures +- **7.3.4** Rollback and undo capabilities -## Testing +### 8. Testing -### Test Strategy +#### 8.1. Test Strategy -- **8.1.1** Testing pyramid (unit, integration, system) -- **8.1.2** Test coverage targets -- **8.1.3** Test environments +- **8.1.1** Testing pyramid: Unit, integration, system, E2E +- **8.1.2** Test coverage targets for different test types +- **8.1.3** Test environments and their configurations +- **8.1.4** CI/CD integration for automated testing -### Test Cases +#### 8.2. Test Cases -- **8.2.1** Critical path tests -- **8.2.2** Edge case tests -- **8.2.3** Regression tests +- **8.2.1** Critical path tests covering core functionality +- **8.2.2** Edge case tests for boundary conditions +- **8.2.3** Regression tests for known issues +- **8.2.4** Performance and load tests if applicable -## Deployment +### 9. Deployment -### Release Process +#### 9.1. Release Process -- **9.1.1** Versioning scheme -- **9.1.2** Release checklist -- **9.1.3** Rollback procedures +- **9.1.1** Versioning scheme (SemVer, CalVer, etc.) +- **9.1.2** Release checklist and required steps +- **9.1.3** Rollback procedures for failed deployments +- **9.1.4** Release notes and changelog requirements -### Distribution +#### 9.2. Distribution -- **9.2.1** Package repositories -- **9.2.2** Installation methods -- **9.2.3** Update mechanisms - -## 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 +- **9.2.1** Package repositories and distribution channels +- **9.2.2** Installation methods for end users +- **9.2.3** Update mechanisms and version management +- **9.2.4** Offline or air-gapped installation options ## Sectionize-Markdown Integration **CRITICAL**: Every SPEC.md file you create or modify MUST follow -sectionize-markdown conventions. +sectionize-markdown conventions completely. 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 +3. Generate or update the TOC with markdown links 4. Ensure all anchors resolve correctly 5. Verify no duplicate IDs exist -Use the sectionize-markdown skill as a reference for detailed conventions. +Use the sectionize-markdown skill as the definitive reference for +all sectionizing conventions and requirements. ## Quality Checklist -Before marking a SPEC as complete: +Before marking a SPEC as complete, verify: -- [ ] **Structure**: All required sections present -- [ ] **Numbering**: All headings and list items numbered correctly -- [ ] **TOC**: Table of contents present and accurate +- [ ] **Structure**: All required sections are present +- [ ] **Numbering**: All headings and list items are numbered correctly +- [ ] **TOC**: Table of contents is present and accurate - [ ] **Status**: Every feature section has a status line -- [ ] **Examples**: Code/config examples provided where applicable -- [ ] **Cross-references**: Links to related sections/files work -- [ ] **Consistency**: Terminology and formatting consistent throughout -- [ ] **Completeness**: All acceptance criteria defined +- [ ] **Examples**: Code and configuration examples are provided +- [ ] **Cross-references**: All internal links resolve correctly +- [ ] **Consistency**: Terminology and formatting are consistent +- [ ] **Completeness**: All acceptance criteria are defined - [ ] **Sectionized**: Follows sectionize-markdown conventions completely ## Maintenance Guidelines - **Versioning**: Increment version in frontmatter with each update -- **Changelog**: Maintain updated/created dates in frontmatter +- **Changelog**: Maintain updated and created dates in frontmatter - **Review**: SPEC should be reviewed before major implementation -- **Sync**: Keep SPEC in sync with implementation (status updates) +- **Sync**: Keep SPEC in sync with implementation (update status) ## Tools and Automation When working with SPEC files: -- Use scripts to verify section numbering -- Automate TOC generation -- Validate all internal links -- Check for duplicate IDs -- Lint markdown formatting +- Use scripts to verify section numbering consistency +- Automate TOC generation to avoid manual errors +- Validate all internal links before committing +- Check for duplicate IDs across the entire document +- Run markdown linters to ensure formatting quality ## Common Pitfalls - **Unnumbered items**: Every list item MUST have a bold ID -- **Broken anchors**: Verify all TOC links resolve +- **Broken anchors**: Always verify all TOC links resolve - **Inconsistent status**: Use consistent status labels throughout - **Missing examples**: Always include examples for data formats -- **Ambiguous requirements**: Requirements must be testable +- **Ambiguous requirements**: Requirements must be testable and verifiable +- **Overly verbose**: Be concise but comprehensive +- **Under-specified**: Include enough detail for implementation