Summary
The developer agent does not always invoke technical-writer before converting a PR from Draft to Ready for Review, despite this being a mandatory gate (Rule 10 in developer.agent.md and Completion Gate item 6). This issue proposes six targeted improvements to structurally enforce the invocation.
Root Cause Analysis
- Weak trigger language (Rule 10 vs Rule 18): Rule 18 (verifier) uses "with no path that skips the call" reinforcement, while Rule 10 (technical-writer) reads as a sequencing constraint only.
- No execution-evidence field in closeout payload: The payload has
verifier_audit: run | blocked but no equivalent technical_writer_run: run | blocked field. Agents can self-report docs_drift_status: clean without ever running the check.
- No explicit planner merge gate for technical-writer execution: Planner verifies
verifier_audit: run as a merge gate, but has no parallel check for technical-writer invocation evidence.
- Positioning at end of long completion sequence: After quality gates and verifier audit, the "feels done" heuristic causes the agent to skip directly to PR conversion.
- Weaker phrasing in
implement.instructions.md: Uses "validation MUST include" (output quality) vs "MUST have run" (execution evidence).
- Missing from summary table: The "GitHub Execution Rules Summary" table in
implement.instructions.md doesn't list technical-writer as a named gate.
Proposed Changes
1. Strengthen Rule 10 language in developer.agent.md
Add "with no path that skips the call. This is not optional and is not gated behind user request" — mirroring Rule 18's language.
2. Add technical_writer_run field to closeout payload
Add a binary technical_writer_run: run | blocked field to the closeout payload schema in both developer.agent.md and planner.agent.md.
3. Add planner merge gate for technical-writer execution
In planner.agent.md Phase 4 merge management rules, add: "Verify technical_writer_run: run — confirms developer invoked the mandatory technical-writer pass."
4. Reorder execution flow: move technical-writer before verifier audit
In developer.agent.md step 7 and implement.instructions.md, swap the order so docs are updated before the verifier runs. This reduces the "feels done after verifier" drop-off and ensures docs are current when the audit inspects them.
5. Make technical-writer a distinct numbered step in Execution Flow
Instead of a bullet among many in step 7, make it an explicit numbered step (e.g., step 8) so it's visually distinct and harder to skip.
6. Add technical-writer to the "GitHub Execution Rules Summary" table
In implement.instructions.md, add technical-writer as a named gate in the "Before closing" row of the summary table.
Acceptance Criteria
Affected Files
.github/agents/developer.agent.md
.github/agents/planner.agent.md
.github/instructions/implement.instructions.md
.kiro/agents/developer.md
.kiro/agents/planner.md (if exists)
.kiro/steering/implement.md (if exists)
.claude/agents/developer.md (if exists)
.claude/agents/planner.md (if exists)
Non-Goals
- Changing
technical-writer agent behavior or output format
- Modifying the drift/stale-doc validation logic itself
- Changing the verifier audit flow
Summary
The
developeragent does not always invoketechnical-writerbefore converting a PR from Draft to Ready for Review, despite this being a mandatory gate (Rule 10 indeveloper.agent.mdand Completion Gate item 6). This issue proposes six targeted improvements to structurally enforce the invocation.Root Cause Analysis
verifier_audit: run | blockedbut no equivalenttechnical_writer_run: run | blockedfield. Agents can self-reportdocs_drift_status: cleanwithout ever running the check.verifier_audit: runas a merge gate, but has no parallel check for technical-writer invocation evidence.implement.instructions.md: Uses "validation MUST include" (output quality) vs "MUST have run" (execution evidence).implement.instructions.mddoesn't listtechnical-writeras a named gate.Proposed Changes
1. Strengthen Rule 10 language in
developer.agent.mdAdd "with no path that skips the call. This is not optional and is not gated behind user request" — mirroring Rule 18's language.
2. Add
technical_writer_runfield to closeout payloadAdd a binary
technical_writer_run: run | blockedfield to the closeout payload schema in bothdeveloper.agent.mdandplanner.agent.md.3. Add planner merge gate for technical-writer execution
In
planner.agent.mdPhase 4 merge management rules, add: "Verifytechnical_writer_run: run— confirms developer invoked the mandatory technical-writer pass."4. Reorder execution flow: move technical-writer before verifier audit
In
developer.agent.mdstep 7 andimplement.instructions.md, swap the order so docs are updated before the verifier runs. This reduces the "feels done after verifier" drop-off and ensures docs are current when the audit inspects them.5. Make technical-writer a distinct numbered step in Execution Flow
Instead of a bullet among many in step 7, make it an explicit numbered step (e.g., step 8) so it's visually distinct and harder to skip.
6. Add technical-writer to the "GitHub Execution Rules Summary" table
In
implement.instructions.md, addtechnical-writeras a named gate in the "Before closing" row of the summary table.Acceptance Criteria
developer.agent.md(both.github/agents/and.kiro/agents/) uses "no path that skips the call" reinforcement languagetechnical_writer_run: run | blockedindeveloper.agent.mdandplanner.agent.md(all platform variants)technical_writer_run: runbefore merging story PRsdeveloper.agent.mdplaces technical-writer invocation before verifier auditimplement.instructions.mdsummary table includes technical-writer as a named gate.github/agents/,.kiro/agents/, and.claude/agents/variantsAffected Files
.github/agents/developer.agent.md.github/agents/planner.agent.md.github/instructions/implement.instructions.md.kiro/agents/developer.md.kiro/agents/planner.md(if exists).kiro/steering/implement.md(if exists).claude/agents/developer.md(if exists).claude/agents/planner.md(if exists)Non-Goals
technical-writeragent behavior or output format