home / skills / peterfile / devpilot-agents / living-documentation

living-documentation skill

This skill helps keep living documentation in sync with code changes by updating specs based on modifications to requirements or design.

npx playbooks add skill peterfile/devpilot-agents --skill living-documentation

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: living-documentation
description: Sync spec files with code changes. Triggers when modifying code that affects .kiro/specs/*/requirements.md or .kiro/specs/*/design.md. Use after implementing features, fixing bugs, or refactoring that changes behavior documented in specs.
---

# Living Documentation

Spec guides generation. Code changes update spec.

## When Triggered

- Modifying code that implements behavior defined in `requirements.md`
- Changing architecture/interfaces described in `design.md`
- Discovering edge cases or patterns not yet documented

## Lifecycle

| Phase    | Authority   | Action                      |
| -------- | ----------- | --------------------------- |
| Generate | Spec → Code | Follow spec as contract     |
| Modify   | Code → Spec | Update spec to reflect code |

## Sync Protocol

After completing code change:

1. **Identify Affected Specs**
   - Check task's `_writes:` manifest
   - Map to spec sections: which requirements/design does this touch?

2. **Update Spec Content**
   - Remove obsolete descriptions
   - Document actual implementation approach
   - Add discovered edge cases as new ACs
   - Keep spec readable without code

3. **Add Traceability**

   ```markdown
   <!-- impl: path/to/file.ts#FunctionName -->
   ```

4. **Commit Together**
   - Spec changes in same commit as code changes

## What to Update

| Code Change           | Spec Update                       |
| --------------------- | --------------------------------- |
| New function/module   | Add to `design.md#Components`     |
| Behavior change       | Update ACs in `requirements.md`   |
| Edge case handling    | Add AC with EARS format           |
| Architecture decision | Document rationale in `design.md` |
| Removed feature       | Delete from both specs            |

## Quality Check

- [ ] Spec describes current reality, not original plan
- [ ] No stale sections left
- [ ] New reader understands system from spec alone
- [ ] Traceability links added

Overview

This skill keeps specification files in sync with code changes by detecting when implementation, architecture, or edge cases diverge from documented requirements and design. It triggers on edits that affect .kiro/specs/*/requirements.md or .kiro/specs/*/design.md and guides you to update specs alongside code. The goal is a living documentation artifact that reflects the current system, not an outdated plan.

How this skill works

When code that implements or alters documented behavior is changed, the skill identifies which spec sections are affected by mapping the task manifest and code locations to requirements and design entries. It guides developers to update requirements.md and design.md with concrete implementation details, new acceptance criteria, edge cases, and traceability links. It recommends committing spec updates in the same commit as the code change and provides a checklist to verify quality and readability.

When to use it

After implementing a feature that touches documented requirements or design
When fixing a bug that reveals an undocumented edge case or behavior change
During refactors that alter interfaces, modules, or architectural boundaries
When removing or deprecating functionality that is still described in specs

Best practices

Identify affected specs before writing changes using the task’s manifest and file map
Document actual implementation choices and rationale in design.md, not future intentions
Add acceptance criteria for discovered edge cases using clear, testable language
Include traceability markers (file path and symbol) to link spec entries to code
Commit spec updates in the same commit as the related code change to preserve history

Example use cases

Implementing a new API endpoint and adding its contract and components to design.md
Refactoring a module interface and updating requirements.md acceptance criteria to match new behavior
Fixing a bug and adding an AC describing the edge case and the conditions that reproduce it
Removing a deprecated feature and cleaning both requirements and design docs to remove stale guidance

FAQ

What exact files trigger the skill?

.kiro/specs/*/requirements.md and .kiro/specs/*/design.md edits trigger the synchronization guidance.

Should spec updates be committed separately?

No. Commit spec changes in the same commit as the code change to preserve traceability between implementation and documentation.

How do I link code to spec entries?

Add a simple traceability marker pointing to the implementation, for example: .