Skip to content

[docs] docs: unbloat ResearchPlanAssignOps pattern (21% reduction) #36503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Jun 2, 2026
+10 −58
Merged

[docs] docs: unbloat ResearchPlanAssignOps pattern (21% reduction) #36503

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 10 additions & 58 deletions docs/src/content/docs/patterns/research-plan-assign-ops.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,57 +104,19 @@ Copilot's pull request is reviewed by a human maintainer. The maintainer checks

## End-to-End Example

The following trace shows the full cycle using `go-fan` as the research driver.
A full cycle driven by `go-fan`:

**Monday 7 AM** — `go-fan` runs and creates a discussion:

> **[go-fan] Go Module Review: spf13/cobra**
>
> Current usage creates a new `Command` per invocation. cobra v1.8 introduced
> `SetContext` for propagating cancellation. Quick wins: pass context through
> subcommands, use `PersistentPreRunE` for shared setup.

**Monday afternoon** — Developer reads the discussion and types:

```
/plan
```

The planner creates a parent tracking issue `[plan] cobra improvements` with three sub-issues:

- `[plan] Pass context through subcommands using cobra SetContext`
- `[plan] Refactor shared setup into PersistentPreRunE`
- `[plan] Add context cancellation tests`

**Monday afternoon** — Developer assigns the first two issues to Copilot. Both open PRs within minutes.

**Tuesday** — Developer reviews PRs, requests a minor change on one, approves the other. Both merge by end of day. The tracking issue closes.
- **Monday 7 AM** — `go-fan` posts a discussion *"[go-fan] Go Module Review: spf13/cobra"* recommending context propagation via cobra's `SetContext` and shared setup via `PersistentPreRunE`.
- **Monday afternoon** — A developer types `/plan` on the discussion. The planner opens a `[plan] cobra improvements` tracking issue with three sub-issues (context propagation, `PersistentPreRunE` refactor, cancellation tests), then assigns the first two to Copilot, which opens PRs within minutes.
- **Tuesday** — The developer reviews the PRs, requests one minor change, and merges both. The tracking issue closes automatically.
Comment on lines +110 to +111

## Workflow Configuration Patterns

### Research: produce one discussion per run

```aw wrap
safe-outputs:
create-discussion:
expires: 1d
category: "research"
max: 1
close-older-discussions: true
```

`close-older-discussions: true` prevents discussion accumulation—only the latest finding stays open for the planner.
The Phase 1 example already shows the core research config (`create-discussion` with `close-older-discussions: true`, plus `cache-memory`). Two more safe-output knobs shape the later phases.

Copy link
Copy Markdown
Contributor Author

@github-actions github-actions Bot Jun 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/grill-with-docs] The transition sentence forward-references Phase 1, which may confuse readers who jump directly to this section from a search or link.

💡 Suggestion

Consider making the sentence self-contained, e.g.:

The research phase uses create-discussion with close-older-discussions: true and optionally cache-memory; the two subsections below cover the plan and assign phases.

This removes the assumption that the reader has just finished reading Phase 1.

### Research: maintain memory across runs
### Plan: group sub-issues

```aw wrap
tools:
cache-memory: true
```

Use `cache-memory` to track state between scheduled runs—which items have been reviewed, trend data, or historical baselines.

### Plan: issue grouping
`group: true` creates the parent tracking issue automatically—do not create it manually:

```aw wrap
safe-outputs:
Expand All @@ -166,11 +128,9 @@ safe-outputs:
group: true
```

`group: true` creates a parent tracking issue automatically. Do not create the parent manually—the workflow handles it.
### Assign: skip planning with `assignees`

### Assign: pre-assign via `assignees`

For research workflows that produce self-contained, well-scoped issues, skip the manual plan phase and assign directly:
When research produces self-contained, well-scoped issues, assign directly and skip the manual plan phase—as `duplicate-code-detector` does for narrow duplication fixes:

```aw wrap
safe-outputs:
Expand All @@ -180,17 +140,9 @@ safe-outputs:
assignees: copilot
```

The `duplicate-code-detector` workflow uses this approach—duplication fixes are narrow enough that a planning phase adds no value.

## Customization

Adapt this pattern by varying:

- **Research focus**: static analysis, performance metrics, documentation quality, security, code duplication, test coverage
- **Frequency**: daily, weekly, on-demand
- **Report format**: discussions (for open-ended findings), issues (for self-contained tasks)
- **Planning approach**: automatic (well-scoped research goes straight to Copilot via `assignees: copilot`) vs. manual (developer reviews before assigning)
- **Assignment method**: pre-assign in the research workflow, bulk-assign via an orchestrator workflow, or assign individually through the GitHub UI
Adapt the pattern by varying the **research focus** (static analysis, performance, documentation quality, security, code duplication, test coverage), the **frequency** (daily, weekly, on-demand), the **report format** (discussions for open-ended findings, issues for self-contained tasks), and the **assignment method** (pre-assign in the research workflow, bulk-assign via an orchestrator, or assign individually through the GitHub UI).

## Limitations

Expand Down
Loading