Files
nvaldez b0f07593b5 phronesis v0.3.0: port the four known skills from vibe-wiki - five bundled total
- fiona 2.2.0 (productivity) with its support files (llm-wiki-mod.md, markdown_rules.md)
- memory 1.0.1 (productivity) with MEMORIES.md template; CRLF converted to LF
- sectionize-markdown 1.2.0 (documentation); category added, minor bump
- specification-writer 1.1.0 (documentation); category added, minor bump
- autotest markdown check: md025 front_matter_title set never-matching, so a
  front-matter 'title' key is not an implicit second h1 (SPEC item 9.6)
- README skills table lists all five; all 7 autotest checks green

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 10:20:04 +01:00

11 KiB

name, description, type, version, category, created, updated
name description type version category created updated
specification-writer Load when writing or updating project specifications (SPEC.md). Expert in creating structured and maintainable specification documents. skill 1.1.0 documentation 2026-11-03 2026-11-19

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 established best practices.

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

Sectionize-Markdown Conventions

Always apply sectionize-markdown conventions to every SPEC.md file. Reference: sectionize-markdown skill

  • 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:

---
name: <Project Name> Specification
version: <semver>
title: Project Spec Sheet
type: specification
created: <YYYY-MM-DD>
updated: <YYYY-MM-DD>
---

# <Project Name> Specification

<!-- toc-start: headings 2..6 -->

- [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)
  - [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)
- [8. Testing](#8-testing)
- [9. Deployment](#9-deployment)

<!-- toc-end -->

This document is the build contract for <Project Name>.
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`.

---

Detailed Section Guidelines

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 or audience
  • 1.1.4 Define the project's mission statement

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

1.3. Non-Goals

  • 1.3.1 Explicitly state what will not be implemented
  • 1.3.2 Clarify boundaries with related projects or systems
  • 1.3.3 Document conscious exclusions and rationale

1.4. Document Conventions

  • 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.)

2. Architecture

2.1. Component Diagram

  • 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

2.2. Data Flow

  • 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

2.3. Module Structure

  • 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

3. Core Contracts

3.1. Interfaces

  • 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.2. Data Structures

  • 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.)

4. Package and Runtime

4.1. 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.2. 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.3. 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

5. Feature Requirements

Organize requirements by feature area. Each feature section should include:

  • 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

6. Configuration Files

For each configuration file, document:

  • 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

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.1.4 Expected vs unexpected errors

7.2. Error Reporting

  • 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

7.3. Recovery Strategies

  • 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

8. Testing

8.1. Test Strategy

  • 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

8.2. Test Cases

  • 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

9. Deployment

9.1. Release Process

  • 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

9.2. Distribution

  • 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 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 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 the definitive reference for all sectionizing conventions and requirements.

Quality Checklist

Before marking a SPEC as complete, verify:

  • 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 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 and created dates in frontmatter
  • Review: SPEC should be reviewed before major implementation
  • Sync: Keep SPEC in sync with implementation (update status)

Tools and Automation

When working with SPEC files:

  • 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: 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 and verifiable
  • Overly verbose: Be concise but comprehensive
  • Under-specified: Include enough detail for implementation