Curate a git-managed project

Before starting, the project needs a connected repository, the Cassis CLI, and access to the issue through the Review screen or MCP. For an app-managed project, use Curate in the web app.

1. Read the issue

Choose the prioritized open issue, then read every occurrence. Check the question, symptom, diagnosis, and any correction the user supplied. Use the full source evidence when the right fix is not obvious.

An ontology_gap needs a definition or relationship. missing_data usually means modeling another source table. Do not rewrite a description when the data itself is absent.

2. Change the context

Create a normal feature branch and edit the files under cassis/. Follow the generated cassis/AGENTS.md modeling guide; use the context file format for exact fields.

git switch -c context/fix-top-seller-ranking

Make the smallest change that fixes the underlying rule for every relevant question, not a special case for one prompt.

3. Prove the change

cassis context fmt
cassis context check
cassis context test -q "the question that was failing"
cassis eval run

Formatting keeps the diff readable, validation catches an invalid tree, the question probe checks the intended fix, and evals catch regressions. If the question should become a regression case, include the candidate SQL and its business assumptions for a domain owner to approve.

4. Open the pull request

The pull request should name the issue, quote the decisive evidence, explain the context change, and include the verification results. The recommended default is independent approval: an agent opens or updates the pull request and stops.

Write Resolves <issue id> in the description, one line per issue the change fixes. cassis issues show prints the exact line, Closes and Fixes work too, and the id’s first 13 characters are enough. This is what closes the loop when the pull request merges, on any branch of the connected repository.

5. Close the loop

After merge, the GitHub App or default-branch CI job publishes the context, and the mentions in the pull request description resolve the issues that started the work. Each one records that it was closed by that pull request, so the trail from issue to change survives.

Confirm the published version carries the fix:

After a GitHub App import, use get_project_status (its latest_git_commit_sha) or cassis status --watch to match the published commit.
After a CLI upload, check the job, then do the same: cassis-cli 3.0.0 and newer record the uploaded commit on the published version, even when the upload changed nothing. With an older CLI, use plain cassis status.

For an outcome that never goes through a pull request, set the status by hand with cassis issues resolve <id> or update_issue_status over MCP. Both need the editor or admin role, so an agent proposes it and a person confirms.

A status change records an outcome; it does not change the context. Resolve only once the published version contains the fix. Dismiss issues you deliberately will not act on, and leave uncertain ones open. An issue nobody closes stays in the triage queue and reads as a gap that was never fixed.

Give the task to an agent

Prompt for an agent Take one detected issue to a pull request

Safe default: open the pull request and stop.

Goal: fix one Cassis issue at its root cause and leave a verified pull request. Read: - https://docs.getcassis.com/raw/curate/agent.md - https://docs.getcassis.com/raw/reference/mcp/issues.md - https://docs.getcassis.com/raw/reference/cli/ontology.md - cassis/AGENTS.md in this checkout Do: 1. Select the prioritized open ontology_gap issue, then read every occurrence and any needed source evidence. 2. Create a feature branch and make the smallest context change that fixes the underlying rule. 3. Run cassis context fmt, cassis context check, cassis context test for the failing question, and cassis eval run. Fix failures. 4. Propose a regression case with candidate SQL and its business assumptions when appropriate; do not approve it yourself. 5. Open a pull request naming the issue, evidence, change, and verification results. 6. If the pull request merges while you are still on the task, confirm the published version contains the fix and propose resolving the issue by id. If it does not merge, end by naming the issue id still to resolve once the fix is published. Stop at the pull request unless the repository owner explicitly authorized merge after required checks. Never publish from the web app. Leave the issue open until the merged change is confirmed in the published version, then propose the resolve instead of leaving it open silently.

A repository owner can explicitly authorize an agent to merge, wait for publication, and resolve the issue. Enforce that authority with repository permissions, required checks, and credential scope; Cassis does not add a separate human-approval gate.