Enable direct file editing in developer-docs-consolidator workflow#3444
Enable direct file editing in developer-docs-consolidator workflow#3444
Conversation
…r workflow Enhanced the workflow to explicitly inform the AI agent that it can: - Directly edit files using edit tools - Create pull requests automatically via safe-outputs Key changes: - Updated Mission statement to clarify agent can apply changes directly - Added prominent note about direct file editing capabilities - Updated Phase 3 to emphasize using edit tools to apply changes - Rewrote Phase 5 to explain two-step process (edit files, then auto-PR) - Updated Success Criteria to emphasize making actual file changes Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
There was a problem hiding this comment.
Pull Request Overview
This PR updates the developer-docs-consolidator workflow to emphasize direct file editing capabilities. The changes clarify that the AI agent should make actual file modifications using available edit tools rather than just identifying and reporting issues, with pull requests being created automatically via the safe-outputs mechanism.
Key changes:
- Updated instructions throughout to emphasize direct file editing over reporting
- Added explicit guidance on using Serena's editing tools and standard edit tools
- Restructured PR creation section into two steps: (1) Apply changes directly to files, (2) PR created automatically
- Added reminders and action items to reinforce the direct editing workflow
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
.github/workflows/developer-docs-consolidator.md |
Updated workflow instructions to emphasize direct file editing, restructured PR creation guidance, and added tool usage clarifications |
.github/workflows/developer-docs-consolidator.lock.yml |
Compiled YAML output reflecting the markdown changes, with prompt split location moved from Guidelines section to middle of PR creation instructions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| PROMPT_EOF | ||
| - name: Append prompt (part 2) | ||
| env: | ||
| GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt | ||
| run: | | ||
| cat >> "$GH_AW_PROMPT" << 'PROMPT_EOF' | ||
| **PR Description** (you should output this for the safe-output processor): |
There was a problem hiding this comment.
The prompt split location has moved from the Guidelines section to the middle of the PR creation instructions. The split now occurs between "PR Title" (end of part 1) and "PR Description" (start of part 2), which separates closely related PR creation content across two prompt parts.
This could cause issues because:
- The PR Title and PR Description are conceptually part of the same instruction block
- The AI agent may not see the full PR creation context in a single prompt part
- The previous split location (before "### Mermaid Diagram Guidelines") was more logical as it separated distinct sections
Consider moving the prompt split to a more logical boundary, such as before the "## Guidelines" section or after the entire "Create Pull Request" section is complete.
|
|
||
| **Use Serena's tools to make the changes:** | ||
| - If the file exists: Use `serena-replace_symbol_body` or standard edit tools to update sections | ||
| - If the file doesn't exist: Use `create` tool to create the new file |
There was a problem hiding this comment.
The workflow instructions reference a "Standard create tool" on lines 312 and 497, but no create tool is configured in the frontmatter. The tools section only includes edit:, which is documented as a file editing tool.
If the edit tool supports file creation, the instructions should clarify this. If a separate tool is needed for file creation, it should be added to the tools: configuration in the frontmatter. Otherwise, these references should be updated to use only the available edit tool or Serena-specific tools.
| - If the file doesn't exist: Use `create` tool to create the new file | |
| - If the file doesn't exist: Use the `edit` tool to create the new file |
| - Standard `create` tool - Create new files | ||
|
|
There was a problem hiding this comment.
The workflow instructions reference a "Standard create tool" which is not configured in the frontmatter. This is a duplicate reference to the same issue found on line 312. Either the create tool needs to be added to the tools configuration, or this reference should be updated to use the available edit tool or Serena-specific tools.
| - Standard `create` tool - Create new files |
The developer-docs-consolidator workflow was analyzing files and reporting what should change, but not actually making changes. The safe-outputs configuration for PR creation was present but the instructions didn't tell the agent to use it.
Changes
edittool to apply changes directly, not just identify issuesreplace_symbol_body,insert_after_symbol, standardedit/create)edittoolsExample
Before:
### 1. Fix Tone Issues For each file with tone issues, use the edit tool to:After:
This enables full autonomous operation: analyze → fix → consolidate → PR.
Original prompt
This section details on the original issue you should resolve
<issue_title>[q] Enable Direct File Editing in Developer Documentation Consolidator</issue_title>
<issue_description># 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.mdEnhanced Mission Statement (lines 56-60):
Updated Phase 3: Content Adjustment (lines 190-220):
edittool to make changes directlyedittool to make these changes in the spec files directly"Completely Rewrote Phase 5 (lines 462-535):
serena-replace_symbol_body,serena-insert_after_symbol, standardeditandcreatetools.github/instructions/developer.instructions.mdUpdated Success Criteria (lines 569-580):
Context
This change was requested in discussion #3416 with the comment:
The safe-output configuration was already present in the workflow frontmatter:
The issue was that the workflow instructions didn't make it clear to the AI agent that it should:
This PR fixes that by making the instructions explicit and actionable.
Expected Improvements
Validation
✅ Workflow compiled successfully using
gh aw compile: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 instructionsNote:
.lock.ymlfile will be regenerated automatically by the compilation system after merge.Review Notes
Please review:
This change makes the developer-docs-consolidator workflow more autonomous and capable of actually applying the improvements it identifies, rather than just reporting them.
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.