Writing for Colony

Colony does not require a special issue template. The analyzer reads the title, body, conversation, repository, and .colony/conventions.md when present. Better input reduces ambiguity, but an issue does not need five mandatory sections or file paths to enter the built-in workflow.

This guidance applies to issues or work items admitted by your configured provider and workflow.

State the outcome

A useful issue usually answers three questions:

1. What problem or user need motivates the change?
2. What observable result should be true when it is complete?
3. Which constraints or non-goals must the implementation respect?

For example:

Pro-plan customers need to export billing history from the Billing page. Add a CSV export containing invoice ID, date, amount, and status. Free-plan customers must not see the control and must receive 403 if they call the endpoint directly. Do not introduce a second billing data store.

This gives analysis room to inspect the architecture while preserving the decisions that matter.

Add verification where it helps

Acceptance criteria and test guidance are useful when correctness is not obvious:

• an observable UI or API result
• an authorization or error-path expectation
• a migration or compatibility constraint
• test cases that must be added or preserved
• a command or environment needed to verify the change

These fields are recommendations, not separate contracts enforced by Colony. The automated reviewer considers issue context and runs only the deterministic commands configured for the repository.

Include known technical constraints

Outcome-oriented writing does not mean hiding valid implementation requirements. Include a specific API, data source, compatibility target, protected path, or architectural boundary when it is genuinely non-negotiable. Distinguish that from a speculative solution the analyzer is free to improve.

Useful:

Use the existing billing-events query; it is the audited source of invoice data.

Over-constrained without explanation:

Add exactly these three classes and call them from this new endpoint.

Reference code when you know it

Accurate file, symbol, API, incident, or prior-PR references help Colony find the right context, especially in a large repository. They are optional. An incorrect path can be worse than no path because it anchors analysis in the wrong subsystem.

Examples:

• packages/dashboard/src/pages/Billing.tsx — current Billing page
• GET /api/billing/history — existing authenticated data path
• PR #418 — established CSV streaming pattern

Scope for an independently reviewable change

Small and medium issues generally require less decomposition and produce easier diffs. Split unrelated outcomes rather than combining them with “and also.” Keep related cross-cutting changes together when splitting would create an unusable intermediate state.

The analyzer classifies ordinary implementation work as small, medium, or large. Epic-scale work can enter planning and create child issues. The Strategist’s max_auto_size is a gate for strategy snapshot proposals; it is not a general issue-intake size limit.

For an epic, describe the overall outcome, important ordering constraints, and how the child results integrate. Colony may decompose it, but it does not enforce your organization’s human ownership or review assignments.

Body, comments, and triggers

Use the issue body as the current specification and comments for conversation and clarifications. Agents can receive comments as context, but comments do not all have the same trigger semantics:

• a human reply after an analyzer question can resume needs-clarification
• an ordinary comment on ready-for-dev does not automatically rerun analysis
• a PR comment does not universally enqueue development
• slash commands explicitly request workflow actions and are validated against the current state

Update a contradictory body so future agents and humans do not have to infer which statement wins.

Common ambiguity

Avoid references whose meaning exists only in the author’s head:

“It should work like before for normal users.”

Name the component, behavior, user category, and relevant prior behavior instead. Also replace unfalsifiable criteria such as “works correctly” or “improve performance” with a visible behavior, measurement, or bounded investigation goal.

If the analyzer asks a question, answer it in a comment. Editing the body is good maintenance, but a reply is what triggers clarification recovery.

Going deeper

• Author — how humans engage with analysis and validation
• The Workflow — actual clarification and reanalysis behavior
• Slash Commands — explicit steering controls