Creating Tasks Intermediate

The quality of the Coding Agent's output depends heavily on how well you describe the task. This lesson covers how to assign issues, write effective descriptions, specify acceptance criteria, monitor progress, and review the generated pull requests.

How to Assign an Issue to Copilot

There are two ways to assign a task to the Coding Agent:

Method 1: Direct Assignment

1. Open or create a GitHub Issue

   Navigate to the repository's Issues tab and create a new issue or open an existing one.

2. Assign to Copilot

   In the right sidebar, click Assignees and select Copilot from the dropdown. Copilot appears as an assignee option in repositories where the Coding Agent is enabled.

Method 2: @copilot Mention

You can also trigger the agent by mentioning @copilot in an issue comment:

@copilot Please implement the changes described in this issue.

# Or with additional context:
@copilot Fix this bug. The error happens in the
validateEmail() function in src/utils/validation.ts.
The regex doesn't handle emails with plus signs.

Writing Good Issue Descriptions

A well-written issue is the single most important factor in getting good results from the Coding Agent. Think of it as writing a specification for a junior developer who has access to your codebase but doesn't know the full context.

Essential Components

Specifying Acceptance Criteria

Acceptance criteria tell the agent when the task is "done." Be explicit about what success looks like:

## Acceptance Criteria

- [ ] GET /api/products accepts `page` and `limit` query parameters
- [ ] Default pagination is page=1, limit=20
- [ ] Response includes `total`, `page`, `limit`, and `totalPages` metadata
- [ ] Invalid page/limit values return 400 with descriptive error message
- [ ] SQL query uses OFFSET/LIMIT (not fetching all records)
- [ ] Unit tests cover: default pagination, custom values, edge cases, invalid input
- [ ] Existing tests continue to pass
- [ ] TypeScript types are updated for the new response shape

Including Context

The more relevant context you provide, the better the agent performs. Here are effective ways to add context:

Code References

Link to specific files, functions, or lines of code that are relevant to the task:

## Relevant Code

- The products route handler is in `src/routes/products.ts` (line 45-60)
- The ProductService class is in `src/services/ProductService.ts`
- The Product model is defined in `src/models/Product.ts`
- Similar pagination exists in `src/routes/orders.ts` - follow the same pattern

## Related Issues

- See #142 for how pagination was implemented for the orders endpoint
- Closes #205 (slow product listing)

Screenshots and Error Messages

For bug fixes, include error messages, stack traces, and screenshots when available:

## Error

When a user enters an email like `user+tag@example.com`,
the validation fails with:

```
ValidationError: Invalid email format
    at validateEmail (src/utils/validation.ts:23)
    at UserController.register (src/controllers/UserController.ts:45)
```

## Expected Behavior

Emails with + signs should be accepted as valid.

## Steps to Reproduce

1. POST /api/auth/register
2. Body: { "email": "test+dev@example.com", "password": "..." }
3. Returns 400 instead of 201

Using Labels and Templates

Labels help the agent understand the nature and priority of the task. Consider creating labels specifically for agent assignments:

Monitoring Agent Progress

After assigning an issue, the agent posts status updates as issue comments. Here is what to expect:

1. Acknowledgment

   The agent posts a comment confirming it has started working on the issue, typically within a few seconds.

2. Analysis phase

   The agent reads the issue, explores the codebase, and identifies relevant files. It may post comments about what it has found.

3. Implementation phase

   The agent writes code, makes changes, and runs tests. This is the longest phase and may take several minutes.

4. Validation phase

   The agent runs the test suite and CI pipeline. If tests fail, it may iterate and fix the issues.

5. PR creation

   Once validation passes, the agent creates a pull request and links it to the issue.

Reviewing the Generated PR

Agent-generated PRs should be reviewed with the same rigor as human-authored PRs. Pay special attention to:

Providing Feedback and Requesting Changes

If the PR needs changes, you can request modifications through standard PR review comments. The agent can respond to feedback:

# Specific and actionable (good):
@copilot This pagination query will be slow on large tables.
Add an index on the `created_at` column and use cursor-based
pagination instead of OFFSET/LIMIT.

# Request a specific change:
@copilot Please add error handling for the case where
`page` is greater than `totalPages`. Return an empty array
with the correct metadata instead of a 404.

# Too vague (bad):
@copilot This doesn't look right. Fix it.

Good vs Bad Task Descriptions

Compare these examples to understand what makes an effective task description:

Bad Example

Good Example