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:
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user