[q] Enable Direct File Editing in Developer Documentation Consolidator

# 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:
```yaml
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 #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](https://github.com/githubnext/gh-aw/actions/runs/19161200282)
---
> [!NOTE]
> This was originally intended as a pull request, but the git push operation failed.
>
> **Workflow Run:** [View run details and download patch artifact](https://github.com/githubnext/gh-aw/actions/runs/19161200282)
>
> The patch file is available as an artifact (`aw.patch`) in the workflow run linked above.
To apply the patch locally:
```sh
# 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
```


<details><summary>Show patch preview (173 of 173 lines)</summary>

```diff
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)
```

</details>

Labels: automation, workflow-optimization
State: closed