Proposal: improve ca-docs-writer — add mandatory Type/Documentation label when creating PRs #3232

Open
opened 2026-04-05 08:07:06 +00:00 by freemo · 2 comments
Owner

Agent Improvement Proposal

Pattern Detected

Type: prompt_improvement
Affected Agent: ca-docs-writer
Evidence:

The system watchdog (issue #3120, cycle 6) has flagged a systemic pattern:

"7 open PRs with ZERO labels: #3165, #3162, #3161, #3151, #3127, #3112, #3101"
"This is a systemic pattern — agents creating PRs without adding required Type/ labels"

Of these 9 label-less PRs (as of this analysis), 4 are documentation PRs created by ca-docs-writer:

  • PR #3162: docs: add providers API reference, update index/architecture/changelog (2026-04-05) — branch docs/ca-docs-writer-2026-04-05-cycle1
  • PR #3127: docs: update CHANGELOG, MCP API, plan CLI, and CI/CD docs for recent merged PRs — branch docs/update-changelog-mcp-plan-ci-2026-04-05
  • PR #3112: docs(timeline): Day 95 schedule adherence refresh (2026-04-05) — branch docs/timeline-day95-refresh-2026-04-05
  • PR #3101: docs: add domain/providers API refs, update CHANGELOG and architecture (2026-04-05) — branch docs/api-domain-providers-changelog-2026-04-05

Additionally, several older merged PRs from docs-writer also had no labels (#2608).

Root Cause

The ca-docs-writer agent prompt has no instructions for adding labels when creating PRs. The agent creates PRs via the Forgejo API but never adds Type/Documentation or any other required labels. The prompt's "Important Rules" section mentions committing and pushing but says nothing about PR metadata (labels, milestones).

Unlike implementation PRs that go through ca-pr-api-creator (which has explicit label-adding instructions), docs PRs are created directly by ca-docs-writer without any label-adding step.

Proposed Change

Add a new instruction to the ca-docs-writer agent prompt in the "Important Rules" section:

9. **Add required labels to every PR you create.** After creating a PR via the
   Forgejo API, you MUST add at minimum:
   - `Type/Documentation` label (mandatory for all docs PRs)
   - `State/Unverified` label (initial state for new PRs)
   Use `forgejo_add_issue_labels` to add these labels immediately after PR creation.

Expected Impact

  • All documentation PRs will have proper Type/Documentation labels from creation
  • The watchdog will stop flagging docs PRs as missing labels
  • Project tracking and filtering by type will work correctly for docs PRs
  • Reduces noise in watchdog reports, making real issues more visible

Risk Assessment

  • Very low risk: This adds a label-adding step that is already standard practice for other PR-creating agents. No behavior change to the documentation generation itself.
  • Potential downside: Slightly more API calls per PR creation (one extra call to add labels). Negligible impact.

This is a proposal from the agent evolver. A human must approve this issue before the change will be implemented. To approve: remove the needs feedback label, add State/Verified, or comment with approval.


Automated by CleverAgents Bot
Supervisor: Agent Evolver | Agent: ca-agent-evolver

## Agent Improvement Proposal ### Pattern Detected **Type**: prompt_improvement **Affected Agent**: ca-docs-writer **Evidence**: The system watchdog (issue #3120, cycle 6) has flagged a systemic pattern: > "7 open PRs with ZERO labels: #3165, #3162, #3161, #3151, #3127, #3112, #3101" > "This is a systemic pattern — agents creating PRs without adding required Type/ labels" Of these 9 label-less PRs (as of this analysis), **4 are documentation PRs created by ca-docs-writer**: - PR #3162: `docs: add providers API reference, update index/architecture/changelog (2026-04-05)` — branch `docs/ca-docs-writer-2026-04-05-cycle1` - PR #3127: `docs: update CHANGELOG, MCP API, plan CLI, and CI/CD docs for recent merged PRs` — branch `docs/update-changelog-mcp-plan-ci-2026-04-05` - PR #3112: `docs(timeline): Day 95 schedule adherence refresh (2026-04-05)` — branch `docs/timeline-day95-refresh-2026-04-05` - PR #3101: `docs: add domain/providers API refs, update CHANGELOG and architecture (2026-04-05)` — branch `docs/api-domain-providers-changelog-2026-04-05` Additionally, several older merged PRs from docs-writer also had no labels (#2608). ### Root Cause The `ca-docs-writer` agent prompt has **no instructions for adding labels when creating PRs**. The agent creates PRs via the Forgejo API but never adds `Type/Documentation` or any other required labels. The prompt's "Important Rules" section mentions committing and pushing but says nothing about PR metadata (labels, milestones). Unlike implementation PRs that go through `ca-pr-api-creator` (which has explicit label-adding instructions), docs PRs are created directly by `ca-docs-writer` without any label-adding step. ### Proposed Change Add a new instruction to the `ca-docs-writer` agent prompt in the "Important Rules" section: ``` 9. **Add required labels to every PR you create.** After creating a PR via the Forgejo API, you MUST add at minimum: - `Type/Documentation` label (mandatory for all docs PRs) - `State/Unverified` label (initial state for new PRs) Use `forgejo_add_issue_labels` to add these labels immediately after PR creation. ``` ### Expected Impact - All documentation PRs will have proper `Type/Documentation` labels from creation - The watchdog will stop flagging docs PRs as missing labels - Project tracking and filtering by type will work correctly for docs PRs - Reduces noise in watchdog reports, making real issues more visible ### Risk Assessment - **Very low risk**: This adds a label-adding step that is already standard practice for other PR-creating agents. No behavior change to the documentation generation itself. - **Potential downside**: Slightly more API calls per PR creation (one extra call to add labels). Negligible impact. --- *This is a proposal from the agent evolver. A human must approve this issue before the change will be implemented. To approve: remove the `needs feedback` label, add `State/Verified`, or comment with approval.* --- **Automated by CleverAgents Bot** Supervisor: Agent Evolver | Agent: ca-agent-evolver
Author
Owner

approved

approved
Author
Owner

Human approval acknowledged. Issue verified and transitioned to State/Verified.

  • State: State/UnverifiedState/Verified
  • Approved by: CTO (human review)
  • Scope: Update ca-docs-writer agent prompt to add mandatory Type/Documentation and State/Unverified labels when creating PRs via the Forgejo API.
  • Next step: This issue is ready for implementation.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: ca-human-liaison

Human approval acknowledged. Issue verified and transitioned to `State/Verified`. - **State**: `State/Unverified` → `State/Verified` - **Approved by**: CTO (human review) - **Scope**: Update `ca-docs-writer` agent prompt to add mandatory `Type/Documentation` and `State/Unverified` labels when creating PRs via the Forgejo API. - **Next step**: This issue is ready for implementation. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: ca-human-liaison
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#3232
No description provided.