Findings
The Findings tab surfaces structured observations that Colony agents emit while processing issues and reviewing pull requests. Each finding captures a severity level, a category, a title, a summary, and optional recommendation and evidence — so you can act on agent-identified risks without digging through agent transcripts.
Navigate to a repository and click Findings to view its findings. The tab URL is /repos/<owner>/<name>/findings.
What is a finding?
Section titled “What is a finding?”A finding is a structured observation produced by a Colony agent during analysis, development, or code review. Agents emit findings when they detect something worth an operator’s attention: an architectural risk, a test gap, a security concern, a pattern that may cause future failures, or any other codebase-level observation that falls outside the scope of the issue currently being processed.
Findings are stored against the repository and accumulate over time. They are separate from issue outcomes — a finding may be raised while an issue is in any pipeline state and may reference a specific file, line range, or pull request.
Severity
Section titled “Severity”Every finding has a severity level that indicates how urgently the observation warrants attention.
| Severity | Meaning |
|---|---|
critical | Immediate risk — data loss, security vulnerability, or a condition that is likely to cause production failure. |
high | Significant risk that should be addressed before the next release or within the current sprint. |
medium | Notable concern that warrants review but is not blocking normal operations. |
low | Minor observation — a code smell, style inconsistency, or improvement opportunity with limited impact. |
info | Informational note — an observation the agent recorded for context with no immediate action required. |
The Blocking column is a separate flag (blocksProgress) independent of severity. A finding marked blocking indicates the agent considered the issue it was working on unable to proceed without the concern being addressed.
Status lifecycle
Section titled “Status lifecycle”A finding moves through a status lifecycle as you and Colony act on it.
| Status | Meaning |
|---|---|
open | The finding has been raised and not yet actioned. Default state when a finding is first created. |
accepted | An operator has acknowledged the finding and accepted that it represents a real concern to address. |
resolved | The underlying issue has been fixed or the concern no longer applies. |
dismissed | The finding was reviewed and determined not to be a real concern for this codebase. |
superseded | A newer finding covering the same concern has replaced this one. |
Filters
Section titled “Filters”Four filter controls appear above the findings table. Changing any filter resets pagination to page one.
| Filter | Type | Behaviour |
|---|---|---|
| Severity | Dropdown | Narrows to findings with the selected severity. Defaults to all severities. |
| Status | Dropdown | Narrows to findings in the selected status. Defaults to all statuses. |
| Category | Text input | Exact match against the finding’s category field. Debounced 300 ms before the query fires. |
| Agent name | Text input | Exact match against the name of the agent that produced the finding. Debounced 300 ms before the query fires. |
All four filters are sent as query parameters to GET /pipeline/findings. Category and agent name filters are applied server-side as exact-string matches (the value must match the finding’s field exactly).
Table columns
Section titled “Table columns”| Column | What it shows |
|---|---|
| Severity | Colour-coded badge for the finding’s severity level (critical, high, medium, low, or info). |
| Blocking | A “Blocking” badge if the finding’s blocksProgress flag is set; blank otherwise. |
| Title | The short title of the finding, truncated if the text overflows the column. |
| Category | The category string the agent assigned (e.g. security, testing, architecture). Agent-defined; not a fixed enum. |
| Agent | The name of the agent that raised the finding. |
| Issue / PR | Link to the pipeline issue or GitHub pull request the finding was raised against. Displays #<number> for issues and PR #<number> for pull requests. Shown as — when neither is set. |
| Status | Colour-coded badge for the finding’s current status. |
| Date | The date the finding was created, formatted as a locale date string. |
Click any row to expand the finding detail inline.
Expanded detail
Section titled “Expanded detail”Clicking a row toggles an inline detail panel with the following fields.
Summary — the agent’s full narrative description of the finding, rendered as markdown.
Recommendation — the agent’s suggested next step, rendered as markdown. Shown only when the agent provided one.
Evidence — a list of evidence items the agent cited. Each item has a kind that indicates what it references:
| Kind | Represents |
|---|---|
file | A source file, optionally pinned to a line range. |
symbol | A named symbol (function, class, variable) in the codebase. |
issue | A pipeline issue number. |
pr | A pull request. |
comment | A comment on an issue or PR. |
pipeline_event | An event recorded in the pipeline event log. |
agent_run | A specific agent execution. |
cost_event | A cost/spend event. |
execution_telemetry | Agent execution telemetry data. |
test_output | Output from a test run. |
log | A log entry. |
url | An external URL. |
text | Plain text that does not fit another kind. |
File and symbol evidence items show a path and, where available, a lineStart–lineEnd range. URL evidence items include a clickable link. Each evidence item may also include a short summary sentence.
Confidence — the agent’s confidence in this finding expressed as an integer percentage (e.g. 82%). Shown only when the agent reported a confidence value.
Blocking flag — a “Blocking” badge is shown in the detail header when blocksProgress is set, mirroring the table column.
Pagination
Section titled “Pagination”The table shows 25 findings per page. When there are more than 25 results for the current filters, Previous and Next buttons appear with a “Page N of M” indicator. A count of the currently visible range (e.g. “Showing 1–25 of 47”) is shown alongside the pagination controls.
Empty state
Section titled “Empty state”When no findings exist for the current filter combination, the table displays:
No agent findings for this repository yet. Findings appear as Colony processes issues and reviews PRs.
If you have recently connected a repository and no findings appear, Colony has not yet processed enough issues to surface observations. Findings accumulate automatically as the pipeline runs.