Proposal: improve docs-writer and timeline-updater — add PR label application after git push to fix unlabeled docs PRs #5001

New issue

Open

opened 2026-04-09 00:36:31 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 00:36:31 +00:00

Owner

Agent Improvement Proposal

Pattern Detected

Type: workflow_fix
Affected Agents: docs-writer, timeline-updater
Evidence: 11+ open docs/timeline PRs have zero labels — these agents bypass pr-api-creator label inheritance

Detailed Evidence

During the current build session (started 2026-04-09), sampling open PRs shows a systemic pattern of docs and timeline PRs with NO labels:

PR	Title	Labels
#4830	docs: document 2026-04-06 to 2026-04-08 agent system improvements	`[]`
#4805	docs: architecture — add Milestone Plan section to specification	`[]`
#4757	docs: v3.8.0 documentation updates	`[]`
#4663	docs(timeline): Day 97 schedule adherence update	`[]`
#4652	docs: add module guides for Sandbox, Correction Attempts	`[]`
#4583	docs: architecture — correct SandboxStrategy protocol name	`[]`
#4578	docs: session-4 documentation updates	`[]`
#4572	docs(timeline): update schedule adherence Day 98	`[]`
#4453	docs(timeline): update schedule adherence Day 98	`[]`
#4381	docs: add InvariantReconciliationActor API docs	`[]`

Root Cause Analysis:

The docs-writer and timeline-updater agents create PRs directly via git push + forgejo_create_pull_request, bypassing the pr-api-creator subagent. The pr-api-creator agent has comprehensive label inheritance logic (inherits Type/, Priority/, MoSCoW/, Points/ from linked issues, adds State/In Review). But docs agents don't use it — they create PRs directly.

Docs PRs typically don't have a linked issue, so there's no issue to inherit labels from. But they still need at minimum:

Type/Documentation label
State/In Review label
Priority/Medium label (default for docs)

Impact:

PRs without labels are invisible to label-based filters
The system watchdog flags label compliance failures
The backlog groomer has to retroactively fix labels on PRs
PR reviewers cannot filter by type

Proposed Change

Add a mandatory post-PR-creation label application step to both docs-writer.md and timeline-updater.md.

After creating a PR (via forgejo_create_pull_request or git push + API), both agents should:

Apply Type/Documentation label to the PR
Apply State/In Review label to the PR
Apply Priority/Medium label to the PR (default for docs)

This can be done via a direct curl call immediately after PR creation:

# Apply labels to newly created PR
curl -s -X PUT "https://git.cleverthis.com/api/v1/repos/$owner/$repo/issues/$pr_number/labels" \
  -H "Authorization: token $FORGEJO_PAT" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["Type/Documentation", "State/In Review", "Priority/Medium"]}'

For timeline-updater.md, the label should be Type/Documentation as timeline updates are documentation changes.

Expected Impact

All future docs and timeline PRs will have proper labels immediately upon creation
System watchdog label compliance checks will pass for docs PRs
Backlog groomer will not need to retroactively fix docs PR labels
PR reviewers can filter docs PRs by type
Reduces noise in watchdog health reports

Risk Assessment

Low risk: Adding labels to PRs is purely additive and does not affect PR functionality
No merge impact: Labels do not affect merge eligibility
Idempotent: Applying labels that are already applied is a no-op
Consistent with pr-api-creator: This brings docs agents in line with the label standards already enforced by pr-api-creator

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: agent-evolver

## Agent Improvement Proposal ### Pattern Detected **Type**: workflow_fix **Affected Agents**: `docs-writer`, `timeline-updater` **Evidence**: 11+ open docs/timeline PRs have zero labels — these agents bypass `pr-api-creator` label inheritance ### Detailed Evidence During the current build session (started 2026-04-09), sampling open PRs shows a systemic pattern of docs and timeline PRs with NO labels: | PR | Title | Labels | |----|-------|--------| | #4830 | docs: document 2026-04-06 to 2026-04-08 agent system improvements | `[]` | | #4805 | docs: architecture — add Milestone Plan section to specification | `[]` | | #4757 | docs: v3.8.0 documentation updates | `[]` | | #4663 | docs(timeline): Day 97 schedule adherence update | `[]` | | #4652 | docs: add module guides for Sandbox, Correction Attempts | `[]` | | #4583 | docs: architecture — correct SandboxStrategy protocol name | `[]` | | #4578 | docs: session-4 documentation updates | `[]` | | #4572 | docs(timeline): update schedule adherence Day 98 | `[]` | | #4453 | docs(timeline): update schedule adherence Day 98 | `[]` | | #4381 | docs: add InvariantReconciliationActor API docs | `[]` | **Root Cause Analysis:** The `docs-writer` and `timeline-updater` agents create PRs directly via `git push` + `forgejo_create_pull_request`, bypassing the `pr-api-creator` subagent. The `pr-api-creator` agent has comprehensive label inheritance logic (inherits Type/*, Priority/*, MoSCoW/*, Points/* from linked issues, adds State/In Review). But docs agents don't use it — they create PRs directly. Docs PRs typically don't have a linked issue, so there's no issue to inherit labels from. But they still need at minimum: - `Type/Documentation` label - `State/In Review` label - `Priority/Medium` label (default for docs) **Impact:** - PRs without labels are invisible to label-based filters - The system watchdog flags label compliance failures - The backlog groomer has to retroactively fix labels on PRs - PR reviewers cannot filter by type ### Proposed Change Add a mandatory post-PR-creation label application step to both `docs-writer.md` and `timeline-updater.md`. After creating a PR (via `forgejo_create_pull_request` or git push + API), both agents should: 1. Apply `Type/Documentation` label to the PR 2. Apply `State/In Review` label to the PR 3. Apply `Priority/Medium` label to the PR (default for docs) This can be done via a direct curl call immediately after PR creation: ```bash # Apply labels to newly created PR curl -s -X PUT "https://git.cleverthis.com/api/v1/repos/$owner/$repo/issues/$pr_number/labels" \ -H "Authorization: token $FORGEJO_PAT" \ -H "Content-Type: application/json" \ -d '{"labels": ["Type/Documentation", "State/In Review", "Priority/Medium"]}' ``` For `timeline-updater.md`, the label should be `Type/Documentation` as timeline updates are documentation changes. ### Expected Impact - All future docs and timeline PRs will have proper labels immediately upon creation - System watchdog label compliance checks will pass for docs PRs - Backlog groomer will not need to retroactively fix docs PR labels - PR reviewers can filter docs PRs by type - Reduces noise in watchdog health reports ### Risk Assessment - **Low risk**: Adding labels to PRs is purely additive and does not affect PR functionality - **No merge impact**: Labels do not affect merge eligibility - **Idempotent**: Applying labels that are already applied is a no-op - **Consistent with pr-api-creator**: This brings docs agents in line with the label standards already enforced by `pr-api-creator` --- *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: agent-evolver

Rows
Columns