From 59d1054e1d6b7ac9245d87d5162e1f9b3ebb5b34 Mon Sep 17 00:00:00 2001 From: nvaldez Date: Tue, 3 Nov 2026 16:27:05 +0100 Subject: [PATCH] Add specification-writer skill for expert SPEC.md creation - Create new skill at src/fiona/data/llm_wiki/utils/skills/specification-writer/ - Provides comprehensive guidance for writing project specifications - Integrates with sectionize-markdown skill for consistent formatting - Includes structure template based on fiona-assistant and agent-cost-estimator patterns - Emphasizes always sectionizing SPEC files with numbered headings and list items - Features quality checklist and maintenance guidelines Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- .../skills/specification-writer/SKILL.md | 286 ++++++++++++++++++ 1 file changed, 286 insertions(+) create mode 100644 src/fiona/data/llm_wiki/utils/skills/specification-writer/SKILL.md 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 new file mode 100644 index 0000000..e518ae9 --- /dev/null +++ b/src/fiona/data/llm_wiki/utils/skills/specification-writer/SKILL.md @@ -0,0 +1,286 @@ +--- +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. +type: skill +version: 1.0.0 +created: 2026-11-03 +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. + +## 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 +- Ensuring specifications follow consistent patterns + +## Core Principles + +**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 + +Use this structure as the foundation for all project specifications: + +```markdown +--- +name: Specification +version: +title: Project Spec Sheet +type: specification +created: +updated: +--- + +# Specification + + + +- [1. Product Overview](#1-product-overview) + - [1.1. Purpose](#11-purpose) + - [1.2. Scope](#12-scope) + - [1.3. Non-Goals](#13-non-goals) + - [1.4. Document Conventions](#14-document-conventions) +- [2. Architecture](#2-architecture) +- [3. Core Contracts](#3-core-contracts) +- [4. Package and Runtime](#4-package-and-runtime) +- [5. Feature Requirements](#5-feature-requirements) +- [6. Configuration Files](#6-configuration-files) +- [7. Error Handling](#7-error-handling) +- [8. Testing](#8-testing) +- [9. Deployment](#9-deployment) + + + +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 + +### 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.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.3. Non-Goals + +- **1.3.1** Explicitly state what will not be implemented +- **1.3.2** Clarify boundaries with related projects + +### 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) + +## 2. Architecture + +### 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.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.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 + +## 3. Core Contracts + +Define the fundamental interfaces and data structures: + +### 3.1. Interface + +- **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 + +- **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 + +### 4.1. Dependencies + +- **4.1.1** Runtime dependencies with versions +- **4.1.2** Development dependencies +- **4.1.3** Optional dependencies + +### 4.2. Entry Points + +- **4.2.1** CLI entry points +- **4.2.2** Library entry points +- **4.2.3** Plugin/extension entry points + +### 4.3. Installation + +- **4.3.1** Installation methods (pip, source, etc.) +- **4.3.2** Platform requirements +- **4.3.3** Verification steps + +## 5. Feature Requirements + +Organize by major feature areas: + +### 5.X. + +- **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 + +## 6. Configuration Files + +### 6.1. + +- **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 + +## 7. Error Handling + +### 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.2. Error Reporting + +- **7.2.1** Logging strategy +- **7.2.2** User notifications +- **7.2.3** Error codes and messages + +### 7.3. Recovery Strategies + +- **7.3.1** Automatic recovery mechanisms +- **7.3.2** Manual recovery procedures +- **7.3.3** Data consistency guarantees + +## 8. Testing + +### 8.1. 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 + +- **8.2.1** Critical path tests +- **8.2.2** Edge case tests +- **8.2.3** Regression tests + +## 9. Deployment + +### 9.1. Release Process + +- **9.1.1** Versioning scheme +- **9.1.2** Release checklist +- **9.1.3** Rollback procedures + +### 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 + +## Sectionize-Markdown Integration + +**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 +4. Ensure all anchors resolve correctly +5. Verify no duplicate IDs exist + +Use the sectionize-markdown skill as a reference for detailed conventions. + +## Quality Checklist + +Before marking a SPEC as complete: + +- [ ] **Structure**: All required sections present +- [ ] **Numbering**: All headings and list items numbered correctly +- [ ] **TOC**: Table of contents 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 +- [ ] **Sectionized**: Follows sectionize-markdown conventions completely + +## Maintenance Guidelines + +- **Versioning**: Increment version in frontmatter with each update +- **Changelog**: Maintain updated/created dates in frontmatter +- **Review**: SPEC should be reviewed before major implementation +- **Sync**: Keep SPEC in sync with implementation (status updates) + +## 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 + +## Common Pitfalls + +- **Unnumbered items**: Every list item MUST have a bold ID +- **Broken anchors**: 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