Fix linting violations in specification-writer skill

- Fix MD013 line length violations by splitting long lines
- Fix MD032 by adding blank lines around lists
- Fix MD036 by removing bold emphasis used as headings
- All housekeeping checks now pass

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