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 <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-03 16:34:25 +01:00
parent b7c173affa
commit def3d2cd6d
@@ -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: <YYYY-MM-DD>
- [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