12 — Issue Management

Issue management

Stood Flows treats every finding as a candidate for an issue — something the team has to act on, comment on, close, or come back to. Every panel supports issue creation through a right-click menu on a row or cell, and every issue carries an anchor that pins it to the exact thing it's about.

There are two backends. They share the same UI; you don't usually need to think about which one you're using.

GitHub-backed issues

When the folder is linked to a GitHub repo, all issue operations go through the gh CLI:

The repo link lives in graph.json as githubOwner + githubRepo. Set it from the Issues tab if the auto-detection (gh repo view) didn't pick it up.

You'll need the gh CLI installed and authenticated (gh auth login). The CLI status (green / red / browse) is in Global Settings, same place as sf.

GitHub issues are real GitHub issues — labels, milestones, assignees all work. They show up in your repo's normal Issues tab. The integration is one-way write: Stood Flows creates and edits issues; you can also act on them on GitHub directly and Stood Flows will pick up changes on next fetch.

CSV-backed issues (no GitHub needed)

When no GitHub repo is linked, Stood Flows stores issues in a local CSV file:

workspaces/<alias>/graphs/<slug>/issues.csv

Same operations — create, edit, comment, close, reopen — all done locally. The CSV has a stable header so it's safe to open in a spreadsheet, but the app expects to be the only writer (concurrent edits will trip up).

This is the offline-by-default mode. Use it when:

The Issues tab UI is identical in both modes.

Anchors — what they are, why they exist

An anchor is a tiny block of metadata embedded in the issue body. It looks like:

<!-- stood-anchor:graph=acme-prod-q3,rt=01234000000xyz,col=score,obj=Opportunity,name=New Business -->

The five fields are:

Anchors are HTML comments — they're invisible in the rendered issue body on GitHub and ignored when reading the CSV file in a spreadsheet. But Stood Flows reads them and uses them to:

  1. Filter — the Issues tab shows a count next to each KPI/DML/IO/Apex node that has open issues anchored to it.

  2. Navigate — clicking View on an issue jumps to the right tab, expands the right tree node, applies the right filter, and highlights the row.

  3. Survive refreshes — record-type IDs and column names stay stable across versions, so an issue anchored to Opportunity.NewBusiness.complexity last quarter is still findable after a refresh that adds new RTs.

You don't write the anchor yourself. Every "Create issue" entry point in the app constructs one for you and pre-fills the body with a sensible title and a description that includes the metric value at creation time.

How to create an issue

Three entry points:

  1. Right-click any KPI cell → "Create issue". Anchor records the (object, RT, column) for that cell.

  2. Right-click a row in DML / Licensing / I/O / Apex → "Create issue". Anchor records the drill path.

  3. Issues tab → New issue (with the form). Used for issues that aren't tied to a specific cell.

The pre-filled body is usually enough — review, tag with labels if needed, save.

Following anchors back

Every issue row in the Issues tab has a View button. Clicking it:

This is the muscle behind "every finding is verifiable". You don't lose the link between a comment from three months ago and the data that caused it.

Practical patterns

Triage flow

  1. Run a fresh Refresh + analyses.

  2. For each high-complexity, low-volume row in the KPI table: right-click → "Create issue" with label retire-candidate.

  3. For each integration in the DML integration bucket you don't recognise: right-click → "Create issue" with label unknown-integration.

  4. For each callout destination with errors >20%: right-click → "Create issue" with label broken-callout.

  5. Hand the resulting Issues tab to the team — every row is grounded in a specific number on a specific version of the data.

Reconciliation flow

After a release:

  1. Refresh.

  2. Open the Issues tab and walk down. For each open issue, click View and confirm the metric has improved (or moved as expected).

  3. Close issues that are resolved; comment on issues that have moved differently than expected.

The anchors mean the metric is always one click away — no copying URLs, no remembering which RT was which.

Migrating between backends

If you start CSV-only and later add a GitHub repo: the existing issues.csv stays where it is. The Issues tab quietly switches to GitHub-backed once githubOwner is set in graph.json. There is no automatic CSV → GitHub migration; you can copy rows over manually if you want them preserved in GitHub.

The reverse — removing the GitHub link — leaves the GitHub issues where they are and switches new issues to CSV. Past issues are still readable via the GitHub website; you just won't see them in the panel any more unless you re-link the repo.

Published with Nuclino