Keep Docs in Sync With a Hook

Documentation goes stale because nothing notices when it does. A hook can notice: point it at your source folder, and Kiro compares the changed code against the documentation and proposes an edit.

When to use this

Use this when you keep hand-written documentation that mirrors code, such as an API reference, a configuration table, or a README command list. Skip it when your documentation is generated from the code already, because the generator is the better tool.

Steps

1. Decide exactly which document mirrors which folder. A hook needs one pair, not a vague instruction to keep everything current. For example, docs/api.md mirrors src/api/.

2. Open the hooks section of the Kiro panel, or find the hook commands in the Command Palette.

3. Create a new hook. Kiro accepts a natural-language description, and the IDE also offers a guided form. Describe the pair explicitly:

   When a file under src/api/ is saved, compare the endpoint
   signatures against docs/api.md. If they disagree, propose an
   edit to docs/api.md only. Never edit files under src/.

4. Choose the file-save trigger and set the pattern to the source folder alone, src/api/**. Do not include docs/** in the trigger, or the hook re-triggers itself.

5. Ask for a proposal, not a commit. The wording above tells the agent to propose an edit. Review the diff like any other change.

6. Save the hook. The configuration lands in .kiro/hooks/ in your workspace. Commit it so the team shares the rule. Put it in ~/.kiro/hooks/ instead if you want it in every project.

7. Add a matching line to steering so the agent knows the pairing outside the hook too, for example “docs/api.md documents every endpoint in src/api/”. See Create your first steering file.

Check it worked

Change an endpoint signature in the source folder and save. The hook should fire and either report that the documentation still matches or propose a specific edit to the documentation file. Then save a file that the pattern does not cover and confirm nothing happens. A hook that fires on everything is worse than no hook.

Common problems

• The hook rewrites source files. Your action was too broad. Name the target file and forbid edits elsewhere in the action text.
• A loop starts. The trigger pattern covers the file the hook writes. Separate them.
• The proposal is always wrong. The agent lacks context about the document’s structure. Add a short steering file that explains how the document is organised.
• It fires on formatter saves. Auto-format on save can trigger the hook repeatedly. Narrow the pattern, or trigger on agent-driven changes only where your version supports it.
• Nobody reviews the proposals. Treat a documentation diff like a code diff. An unreviewed automated edit is a future bug report.

Related

• Hooks covers every trigger type and the creation flow.
• Run tests on save with a hook is the companion recipe.
• Advanced Tutorial shows both hooks inside a full workflow.