Author

You are Colony’s PM. Your output is the issue; your input is the business need. The quality of your issue directly determines the reliability of Colony’s output.

If this is you: product managers, product owners, tech leads briefing work for their teams, support engineers filing reproducible bugs, anyone who would normally write a ticket for another human.

What this role does

1. File — write issues with the context, requirements, and acceptance criteria Colony can act on
2. Clarify — respond to analyzer questions when the proposed scope is ambiguous
3. Accept the plan — review and refine the analyzer’s proposed implementation plan before development starts
4. Validate against acceptance criteria — confirm the merged PR delivered what you asked for

File

A Colony-actionable issue has five elements. Skip any of them and the analyzer will either guess (sometimes well, sometimes poorly) or come back asking for clarification.

1. Context

Why this work is needed and what problem it solves. One paragraph. Anchor in business or user terms, not implementation terms.

Good: “Customers on the Pro plan can’t export their billing history. Support has fielded 12 tickets this month asking for it; they’re forwarding to engineering as one-offs.”

Bad: “Add a CSV export endpoint.”

2. Requirements

Specific, measurable outcomes. Bulleted, not prose.

• Customers on the Pro plan see an “Export billing history” button on the Billing page
• The export downloads a CSV with one row per invoice
• The CSV includes: invoice ID, date, amount, status, line items
• Customers on the Free plan see no button and cannot reach the endpoint

3. Acceptance criteria

The conditions under which the work is considered done. Treat these as the test the Reviewer will run.

• Manually exporting from the Billing page produces a CSV that opens cleanly in Excel and Google Sheets
• A Free-plan customer’s request to the endpoint returns 403
• The new button is wired through to a Stripe billing-events query, not a separate data store

4. Test criteria

How correctness should be verified. Distinct from acceptance criteria — these are for the developer, not the Reviewer.

• Unit tests cover plan-gating (Free returns 403, Pro returns 200)
• Integration test exports a CSV from a seeded customer with three invoices and verifies row count and column shape
• No regression in existing billing-page tests

5. File references

Relevant files, modules, or APIs within the repo. Anchors the analyzer’s reading.

• packages/dashboard/src/pages/Billing.tsx — where the button goes
• packages/api/src/routes/billing.ts — where the endpoint goes
• packages/shared/src/billing.ts — types

Anti-pattern: the vague issue

“Fix the billing export.” → Colony has no anchor. The analyzer will ask for the five elements above before doing anything. Filing the vague version costs you a round-trip; filing the structured version costs you ten minutes once.

Clarify

When the analyzer can’t act on what you wrote, it comments on the issue listing what it needs. Read the comment and add the missing pieces — either by editing the issue body or replying in a comment. Once you do, the analyzer re-runs automatically.

You don’t need to re-trigger anything. Don’t close-and-refile unless the scope changed fundamentally.

Accept the plan

For non-epic issues, the analyzer publishes its plan as an issue comment and proceeds to development immediately. You can refine the scope by commenting before development starts; the planner re-runs.

For epic-scale issues, the planner produces a decomposition — a list of subtasks, each filed as its own issue. Read the decomposition. Confirm:

• The subtasks add up to the epic’s intent
• Subtask order matches what’s actually buildable
• No subtask is so large it should itself be an epic

If the decomposition is wrong, comment with corrections; the planner re-runs.

Validate against acceptance criteria

When Colony’s reviewer transitions a PR to human-review-ready (or after auto-merge if the PR was straightforward), check the result against the acceptance criteria you wrote. Three outcomes:

• Match. Approve, merge, close.
• Mismatch. Comment on the PR with the gap. The Reviewer escalates or sends the PR back for a different approach.
• Acceptance criteria themselves were wrong. Re-file as a new issue with corrected criteria. Don’t try to retrofit a half-done PR; that produces worse code than starting over.

Where you engage in the Workflow

• Phase 1: Intake — file the issue, respond to clarifications
• Phase 2: Planning & Dispatch — accept or refine the plan
• Phase 4: Review — validate against acceptance criteria

Your tools

• GitHub issues — where you author. Use issue templates if your repo provides them.
• GitHub comments — where you clarify and accept the plan. Colony reads comments live.
• Acceptance-criteria checklists — Markdown checkboxes in the issue body. The Reviewer can use them to drive validation.

Anti-patterns

• Filing “fix this somewhere in the codebase.” The analyzer can’t anchor scope. Always include file references.
• Putting acceptance criteria in code-comments rather than the issue. The Reviewer doesn’t see code-comments at the right time. Put criteria in the issue body.
• Re-filing because Colony is “stuck.” Most stalls aren’t your problem — comment in the issue and let the Operator recover. Re-filing creates duplicate work and breaks the audit trail.
• Approving the analyzer’s plan without reading it. The plan is your last cheap chance to redirect scope before development burns budget.
• Editing the PR description to “move on.” PR descriptions are generated; if you edit them, the audit record diverges. Comment instead.

Going deeper

• The Workflow — see how your work fits the larger pipeline
• Reviewer role — the human you hand off to in Phase 4
• Reference: issue schema (when published) — the formal issue field requirements