writing-conformant-specs

name	writing-conformant-specs
description	This skill should be used when creating new RFC 2119-conformant specification documents, iterating on specification drafts, choosing keywords (MUST/SHOULD/MAY/MUST NOT) while writing, structuring sections, or progressively refining specifications.

Writing Conformant Specifications

Guides creation and iteration of RFC 2119-conformant specifications. Supports active writing: structuring documents, choosing keywords as requirements are drafted, separating normative from informative content, and progressively refining through iteration.

When to Use

This skill should be used when:

• Creating new specification documents from scratch
• Iterating on specification drafts to improve conformance
• Drafting requirements and choosing appropriate keywords
• Structuring specification sections
• Converting plain language to RFC 2119 format
• Separating normative requirements from informative guidance
• Progressively refining specifications section-by-section

Instructions

1. Load Reference Guide

Read references/rfc-2119-guide.md for keyword definitions, decision tree, structure patterns, normative/informative separation patterns, validation checklist, and examples.

2. Support Creation and Iteration

Primary use case: Help create conformant specifications through active writing and iteration.

Creating: Guide structure, suggest patterns (Conformance Levels, Content Focus, Typical Content + Requirements), help draft with keywords, establish normative/informative separation, reference plan-spec.md and tasklist-spec.md examples.

Iterating: Convert plain language to RFC 2119 requirements, refine keyword choices, add informative labels, restructure for clarity, validate and suggest refinements.

Quick assistance: Answer keyword questions during writing, provide labeling guidance, clarify normative vs informative, suggest patterns, reference decision tree.

Validation: Check conformance when ready, identify violations with line numbers, count keywords, suggest improvements.

3. Iterative Writing Workflow

Support this cycle: Draft section → Keyword requirements → Label informative content → Validate → Refine → Next section

Provide guidance at any step. Support jumping between steps as writing progresses naturally.

4. Apply Decision Tree

Is requirement critical for correctness/safety/core functionality?
├─ Yes → MUST / MUST NOT
└─ No → Strongly recommended for quality?
    ├─ Yes → SHOULD / SHOULD NOT
    └─ No → Completely optional?
        └─ Yes → MAY / OPTIONAL

Provide keyword with example in context, rationale, reference to similar usage, and consideration of what happens if not met.

5. Reference Common Patterns

From guide: Conformance Levels (Level 1/2/3), Content Focus (MUST/MUST NOT), Typical Content + Requirements (separation), Common Mistakes → Best Practices (educational). See references/rfc-2119-guide.md for detailed examples and code.

6. Common Workflows

Write requirements section: Suggest structure pattern, help draft with keywords, separate examples from requirements, validate.

Choose keywords while drafting: Read draft, apply decision tree, suggest keywords with rationale, show transformation, explain implications.

Convert plain language to RFC 2119: Identify requirements vs explanations vs examples, apply keywords, add informative labels, structure using patterns, validate.

Structure specification: Understand scope, suggest conformance level approach, recommend organization, reference plan-spec.md or tasklist-spec.md, provide template.

Make draft conformant: Identify plain imperatives → RFC keywords, unlabeled examples → informative labels, subjective terms → measurable criteria, validate, refine.

Refine keyword strength: Analyze context, apply decision tree (what if not met?), consider conformance implications, recommend with rationale.

7. Provide Actionable Guidance

Structuring: Section organization from patterns, templates with RFC 2119 structure, references to similar specs.

Keywords: Specific keyword with context example, WHY it matches criticality, before/after, what happens if violated.

Separation: Identify normative (requirements) vs informative (guidance/examples), exact labels ("(Informative)", "Best Practice:", "Tip:"), placement, restructure if needed.

Iteration: Read draft, identify improvements, prioritize (critical first), refine section-by-section, validate and iterate.

Validation: Run checklist, report keyword counts, list issues with fixes, assess conformance, suggest next improvements.

Resource Structure

Self-contained with bundled resources:

• SKILL.md - Core instructions for creation and iteration
• references/rfc-2119-guide.md - Complete reference (12K): definitions, decision tree, patterns, validation checklist, examples, external resources

Load reference guide for detailed patterns and validation criteria.

---

Support active creation and iterative refinement. Write conformant specifications correctly from the start, then progressively improve.