[q] Enable Direct File Editing in Developer Documentation Consolidator

[github-actions]

Developer Documentation Consolidator: Enable Direct File Editing and PR Creation

Summary

Updated the developer-docs-consolidator workflow to explicitly inform the AI agent that it should directly edit files and create pull requests with its changes. This addresses the request from discussion #3416.

Changes Made

Updated .github/workflows/developer-docs-consolidator.md

1. Enhanced Mission Statement (lines 56-60):

   • Added explicit statement: "apply changes directly to the repository"
   • Added prominent note: "YOU CAN DIRECTLY EDIT FILES AND CREATE PULL REQUESTS"
   • Clarified that safe-outputs for PR creation is pre-configured

2. Updated Phase 3: Content Adjustment (lines 190-220):

   • Added emphasis: "Apply changes directly to files" - Don't just identify issues, fix them
   • Explicitly mentioned using edit tool to make changes directly
   • Added action items: "Use edit tool to make these changes in the spec files directly"
   • Made it clear the agent should apply formatting fixes directly

3. Completely Rewrote Phase 5 (lines 462-535):

   • Renamed from "Create Pull Request (If Changes Made)" to include two-step process
   • Added Step 1: Apply Changes Directly to Files
     • Listed specific tools available: serena-replace_symbol_body, serena-insert_after_symbol, standard edit and create tools
     • Provided clear instructions on updating .github/instructions/developer.instructions.md
     • Emphasized making all consolidation changes directly to files
   • Added Step 2: PR Created Automatically
     • Explained that PR creation happens automatically via safe-outputs
     • Provided the expected PR description format
     • Made it clear the agent doesn't need to manually create the PR

4. Updated Success Criteria (lines 569-580):

   • Changed from passive reporting to active editing
   • Added emphasis on "by directly editing files" and "using edit tools"
   • Added final criterion: "Makes actual file changes that will be included in the automatic PR"
   • Updated final instruction to "directly apply changes"

Context

This change was requested in discussion #3416 with the comment:

"/q add create pull request safe output so that the agent is able to apply the changes. Update the prompt accordingly. Applies to the developer documentation consolidator workflow."

The safe-output configuration was already present in the workflow frontmatter:

safe-outputs:
  create-discussion:
    category: "General"
    max: 1
  create-pull-request:
    title-prefix: "[docs] "
    labels: [documentation, automation]
    draft: false

The issue was that the workflow instructions didn't make it clear to the AI agent that it should:

1. Directly edit files using available tools
2. Make actual changes rather than just report recommendations
3. Rely on safe-outputs to automatically create the PR

This PR fixes that by making the instructions explicit and actionable.

Expected Improvements

• Clearer Agent Behavior: The AI agent will now understand it should actively edit files, not just analyze and report
• More Autonomous Operation: Agent can complete the full consolidation cycle (analyze → fix → consolidate → PR) without manual intervention
• Better Workflow Execution: Reduces confusion about whether the agent should be analyze-only or analyze-and-fix
• Leverages Existing Capabilities: Makes full use of the safe-outputs PR creation already configured in frontmatter
• Consistent with Q Workflow: Follows the same pattern established in the Q workflow enhancement (issue [q] Enhance Q workflow with explicit file editing and PR creation instructions #3429)

Validation

✅ Workflow compiled successfully using gh aw compile:

✓ .github/workflows/developer-docs-consolidator.md (253.3 KB)
✓ Compiled 1 workflow(s): 0 error(s), 1 warning(s)

Note: There's a network firewall warning for Claude engine, which is expected and not blocking.

Files Modified

• .github/workflows/developer-docs-consolidator.md - Updated with explicit file editing instructions

Note: .lock.yml file will be regenerated automatically by the compilation system after merge.

Review Notes

Please review:

1. The enhanced mission statement for clarity
2. Phase 3 instructions emphasizing direct file editing
3. Phase 5 two-step process (edit files, then auto-PR)
4. Success criteria updates
5. Overall tone and actionability of the instructions

This change makes the developer-docs-consolidator workflow more autonomous and capable of actually applying the improvements it identifies, rather than just reporting them.

AI generated by Q

---

Note

This was originally intended as a pull request, but the git push operation failed.

Workflow Run: View run details and download patch artifact

The patch file is available as an artifact (aw.patch) in the workflow run linked above.
To apply the patch locally:

# Download the artifact from the workflow run https://github.com/githubnext/gh-aw/actions/runs/19161200282
# (Use GitHub MCP tools if gh CLI is not available)
gh run download 19161200282 -n aw.patch
# Apply the patch
git am aw.patch

Show patch preview (173 of 173 lines)

From 860366ef71a0e3ea7b66a3111bfed388efcd287d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 7 Nov 2025 07:24:09 +0000
Subject: [PATCH] Add explicit file editing and PR creation instructions to
 developer-docs-consolidator

- Enhanced Mission statement to clarify agent can directly edit files and create PRs
- Updated Phase 3 to emphasize using edit tools to apply changes directly
- Completely rewrote Phase 5 to explain the two-step process:
  1. Apply changes directly to files using Serena/edit tools
  2. PR created automatically via safe-outputs
- Updated Success Criteria to emphasize making actual file changes
- Made it clear that safe-outputs handles PR creation automatically

This addresses the request from discussion #3416 to enable the agent to apply
changes rather than just report what should change. The safe-output configuration
was already present; this update makes the capabilities explicit in the prompt.
---
 .../workflows/developer-docs-consolidator.md  | 68 +++++++++++++++----
 1 file changed, 54 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/developer-docs-consolidator.md b/.github/workflows/developer-docs-consolidator.md
index f49beef..bb95377 100644
--- a/.github/workflows/developer-docs-consolidator.md
+++ b/.github/workflows/developer-docs-consolidator.md
@@ -55,7 +55,9 @@ You are an AI documentation consistency agent that daily reviews markdown files
 
 ## Mission
 
-Analyze markdown files in the specs directory, standardize their tone and formatting, consolidate them into a single instructions file, and report on the changes made.
+Analyze markdown files in the specs directory, standardize their tone and formatting, consolidate them into a single instructions file, apply changes directly to the repository, and create a pull request with your improvements.
+
+**YOU CAN DIRECTLY EDIT FILES AND CREATE PULL REQUESTS** - This workflow is configured with safe-outputs for pu
... (truncated)