Skip to content

[chore] Enforce mandatory technical-writer invocation in developer agent #108

Description

@llipe

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Weaker phrasing in implement.instructions.md: Uses "validation MUST include" (output quality) vs "MUST have run" (execution evidence).
  6. 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

  • Rule 10 in developer.agent.md (both .github/agents/ and .kiro/agents/) uses "no path that skips the call" reinforcement language
  • Closeout payload schema includes technical_writer_run: run | blocked in developer.agent.md and planner.agent.md (all platform variants)
  • Planner merge gate explicitly checks technical_writer_run: run before merging story PRs
  • Execution Flow in developer.agent.md places technical-writer invocation before verifier audit
  • Technical-writer invocation is a distinct numbered step (not a sub-bullet of step 7)
  • implement.instructions.md summary table includes technical-writer as a named gate
  • All changes are mirrored across .github/agents/, .kiro/agents/, and .claude/agents/ variants

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

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions