Update specification
Revise an existing solution specification so it remains clear, unambiguous, machine-readable, self-contained, and aligned with new requirements or implemented code.
When to invoke
- "Update this specification with the new requirements."
- "Sync the spec with the code changes."
- "Revise /spec/schema-user-profile.md for this interface change."
- "Apply AI-ready specification best practices to this existing spec."
- "Add acceptance criteria and validation to this spec."
Inputs
Use $ARGUMENTS as the target specification path, change request, or code-change summary. If a concrete file is not provided, identify the likely existing /spec/ file from user context and ask for clarification only when multiple candidates remain.
AI-ready specification rules
| Rule |
Apply it by |
| Precise language |
Use explicit, testable statements; avoid idioms, metaphors, and context-dependent references. |
| Clear classification |
Distinguish requirements, constraints, guidelines, patterns, recommendations, interfaces, and dependencies. |
| Structured formatting |
Use headings, lists, tables, and code blocks so Generative AIs can parse the file reliably. |
| Defined terms |
Define all acronyms, abbreviations, and domain-specific terms. |
| Self-contained context |
Include examples, edge cases, rationale, and dependencies needed to use the spec without hidden context. |
| Well formed Markdown |
Keep frontmatter, headings, tables, and fences syntactically valid. |
File naming
The specification must stay in /spec/ and use [a-z0-9-]+.md. The name should describe the content and start with one high-level purpose: schema, tool, data, infrastructure, process, architecture, or design.
Specification structure
Update the file so these sections are present and filled appropriately:
| Section |
Required content |
| Frontmatter |
title, optional version, date_created, optional last_updated, optional owner, optional tags. |
# Introduction |
Short introduction and goal. |
## 1. Purpose & Scope |
Purpose, scope, audience, and assumptions. |
## 2. Definitions |
Acronyms, abbreviations, and domain terms. |
## 3. Requirements, Constraints & Guidelines |
REQ-001, SEC-001, [3 LETTERS]-001, CON-001, GUD-001, and PAT-001 style entries as applicable. |
## 4. Interfaces & Data Contracts |
Interfaces, APIs, schemas, examples, or integration points. |
## 5. Acceptance Criteria |
AC-001 entries in Given-When-Then format where appropriate. |
## 6. Test Automation Strategy |
Test Levels, Frameworks such as MSTest, FluentAssertions, and Moq when applicable, Test Data Management, CI/CD Integration, Coverage Requirements, and Performance Testing. |
## 7. Rationale & Context |
Reasoning behind requirements, constraints, and guidelines. |
## 8. Dependencies & External Integrations |
External Systems, Third-Party Services, Infrastructure Dependencies, Data Dependencies, Technology Platform Dependencies, and Compliance Dependencies. |
## 9. Examples & Edge Cases |
Code or data examples, including edge cases. |
## 10. Validation Criteria |
Criteria or tests required for compliance. |
## 11. Related Specifications / Further Reading |
Related specs and relevant external documentation. |
Dependencies should focus on architectural and business needs, not package implementation details. For example, specify OAuth 2.0 authentication library rather than Microsoft.AspNetCore.Authentication.JwtBearer v6.0.1 unless a version is an architectural constraint.
Procedure
- Read the existing specification file and the new requirement or code-change evidence.
- Preserve stable identifiers unless the meaning changes. Add new IDs sequentially.
- Update frontmatter, including
last_updated when appropriate.
- Revise affected requirements, constraints, interfaces, acceptance criteria, dependencies, examples, and validation criteria.
- Ensure every new or changed requirement has acceptance criteria and validation coverage.
- Save the updated spec in
/spec/ with the required filename convention.
- Report changed sections and any unresolved assumptions.
Legacy placeholders
Older invocations may name the target as ${file} and ask for ai-ready specifications. Preserve frontmatter placeholder meanings such as Team/Individual, YYYY-MM-DD, and Platform/runtime while replacing them with concrete values in the updated file.
Output template
## Specification update result
**Status:** updated | needs clarification | blocked
**Specification:** `/spec/<purpose-name>.md`
**Change source:** <requirements, code files, or user request>
### Sections changed
| Section | Change summary | Requirement IDs affected |
| --- | --- | --- |
| `<section>` | `<summary>` | `<REQ/SEC/CON/GUD/PAT/AC IDs>` |
### Validation
- Filename convention `[a-z0-9-]+.md`: pass | fail
- Required sections present: pass | fail
- New or changed requirements have acceptance criteria: pass | fail
- Markdown and frontmatter well formed: pass | fail
### Follow-up
<unresolved assumptions or `None`>
Quality gate
1---2name: update-specification-23description: Update an existing AI-ready specification file in /spec/ from new requirements or code changes, preserving precise requirements, constraints, interfaces, acceptance criteria, and validation structure. Use this skill when the user asks to update a specification, revise requirements, sync a spec with code, or apply best practices for AI-ready specifications.4---56# Update specification78Revise an existing solution specification so it remains clear, unambiguous, machine-readable, self-contained, and aligned with new requirements or implemented code.910## When to invoke1112- "Update this specification with the new requirements."13- "Sync the spec with the code changes."14- "Revise /spec/schema-user-profile.md for this interface change."15- "Apply AI-ready specification best practices to this existing spec."16- "Add acceptance criteria and validation to this spec."1718## Inputs1920Use `$ARGUMENTS` as the target specification path, change request, or code-change summary. If a concrete file is not provided, identify the likely existing `/spec/` file from user context and ask for clarification only when multiple candidates remain.2122## AI-ready specification rules2324| Rule | Apply it by |25| --- | --- |26| Precise language | Use explicit, testable statements; avoid idioms, metaphors, and context-dependent references. |27| Clear classification | Distinguish requirements, constraints, guidelines, patterns, recommendations, interfaces, and dependencies. |28| Structured formatting | Use headings, lists, tables, and code blocks so Generative AIs can parse the file reliably. |29| Defined terms | Define all acronyms, abbreviations, and domain-specific terms. |30| Self-contained context | Include examples, edge cases, rationale, and dependencies needed to use the spec without hidden context. |31| Well formed Markdown | Keep frontmatter, headings, tables, and fences syntactically valid. |3233## File naming3435The specification must stay in `/spec/` and use `[a-z0-9-]+.md`. The name should describe the content and start with one high-level purpose: `schema`, `tool`, `data`, `infrastructure`, `process`, `architecture`, or `design`.3637## Specification structure3839Update the file so these sections are present and filled appropriately:4041| Section | Required content |42| --- | --- |43| Frontmatter | `title`, optional `version`, `date_created`, optional `last_updated`, optional `owner`, optional `tags`. |44| `# Introduction` | Short introduction and goal. |45| `## 1. Purpose & Scope` | Purpose, scope, audience, and assumptions. |46| `## 2. Definitions` | Acronyms, abbreviations, and domain terms. |47| `## 3. Requirements, Constraints & Guidelines` | `REQ-001`, `SEC-001`, `[3 LETTERS]-001`, `CON-001`, `GUD-001`, and `PAT-001` style entries as applicable. |48| `## 4. Interfaces & Data Contracts` | Interfaces, APIs, schemas, examples, or integration points. |49| `## 5. Acceptance Criteria` | `AC-001` entries in Given-When-Then format where appropriate. |50| `## 6. Test Automation Strategy` | Test Levels, Frameworks such as MSTest, FluentAssertions, and Moq when applicable, Test Data Management, CI/CD Integration, Coverage Requirements, and Performance Testing. |51| `## 7. Rationale & Context` | Reasoning behind requirements, constraints, and guidelines. |52| `## 8. Dependencies & External Integrations` | External Systems, Third-Party Services, Infrastructure Dependencies, Data Dependencies, Technology Platform Dependencies, and Compliance Dependencies. |53| `## 9. Examples & Edge Cases` | Code or data examples, including edge cases. |54| `## 10. Validation Criteria` | Criteria or tests required for compliance. |55| `## 11. Related Specifications / Further Reading` | Related specs and relevant external documentation. |5657Dependencies should focus on architectural and business needs, not package implementation details. For example, specify `OAuth 2.0 authentication library` rather than `Microsoft.AspNetCore.Authentication.JwtBearer v6.0.1` unless a version is an architectural constraint.5859## Procedure60611. Read the existing specification file and the new requirement or code-change evidence.622. Preserve stable identifiers unless the meaning changes. Add new IDs sequentially.633. Update frontmatter, including `last_updated` when appropriate.644. Revise affected requirements, constraints, interfaces, acceptance criteria, dependencies, examples, and validation criteria.655. Ensure every new or changed requirement has acceptance criteria and validation coverage.666. Save the updated spec in `/spec/` with the required filename convention.677. Report changed sections and any unresolved assumptions.6869## Legacy placeholders7071Older invocations may name the target as `${file}` and ask for `ai-ready` specifications. Preserve frontmatter placeholder meanings such as `Team/Individual`, `YYYY-MM-DD`, and `Platform/runtime` while replacing them with concrete values in the updated file.7273## Output template7475```markdown76## Specification update result7778**Status:** updated | needs clarification | blocked79**Specification:** `/spec/<purpose-name>.md`80**Change source:** <requirements, code files, or user request>8182### Sections changed83| Section | Change summary | Requirement IDs affected |84| --- | --- | --- |85| `<section>` | `<summary>` | `<REQ/SEC/CON/GUD/PAT/AC IDs>` |8687### Validation88- Filename convention `[a-z0-9-]+.md`: pass | fail89- Required sections present: pass | fail90- New or changed requirements have acceptance criteria: pass | fail91- Markdown and frontmatter well formed: pass | fail9293### Follow-up94<unresolved assumptions or `None`>95```9697## Quality gate9899- [ ] The existing specification file was read before editing.100- [ ] The file remains under `/spec/` and follows `[a-z0-9-]+.md` with an approved purpose prefix.101- [ ] All required sections are present and populated.102- [ ] Requirements, constraints, guidelines, patterns, and acceptance criteria use stable IDs.103- [ ] New or changed requirements have testable acceptance criteria and validation criteria.104- [ ] Dependencies describe architectural or business needs rather than unnecessary package versions.105- [ ] The document is self-contained, unambiguous, and well formed Markdown.
paulasilvatech