# Contributing to Tracefinity

Thanks for helping with Tracefinity. The project stays useful by doing one job
well, so substantial features need a quick product check before anyone spends a
week building them.

## Read before changing things

- [CONSTITUTION.md](CONSTITUTION.md) defines the product boundary and how feature
  requests are classified.
- [DESIGN.md](DESIGN.md) contains the engineering principles that apply once a
  change belongs in the product.
- [README.md](README.md) covers setup and day-to-day development.
- The relevant file under [docs/](docs/) carries deeper architecture, API,
  geometry, and workflow details.

## Before building a feature

Open or find an issue before implementing a substantial feature, new workflow,
integration, input mode, or output mode. Describe the outcome you need, not only
the implementation you have in mind. This gives us a chance to check the
constitution, find a smaller solution, and avoid wasting a contributor's time.

Small bug fixes and clearly aligned refinements do not need ceremony. If the
boundary is unclear, opening an issue is enough; you are not expected to argue a
legal case for the feature.

Agents should use the repository's `scope-triage` skill when evaluating feature
requests. The skill advises; Jason makes the final call.

## Scope and backlog state

Scope says whether an idea belongs in Tracefinity. Open or closed says whether
we currently plan to work on it. Those are different decisions.

| Label | Meaning |
|-|-|
| `scope:in-scope` | Eligible for prioritisation, not promised |
| `scope:needs-decision` | Exposes or changes a constitutional boundary |
| `scope:out-of-scope` | Conflicts with a settled boundary |
| `status:needs-demand` | Fits, but current interest does not justify the work |
| `status:blocked-by-cost` | Fits, but the implementation or maintenance burden is disproportionate |
| `status:needs-retriage` | New interest in a closed request needs human review |

An issue can be in scope and still be closed as `Not planned`. A canonical
scope request is an issue carrying one of the three `scope:*` verdict labels.
Closed canonical requests stay unlocked so reactions, concrete use cases, and
related requests can provide evidence for re-triage. `status:needs-retriage`
only flags that evidence for a person to assess; it does not change the existing
scope decision or reopen the request automatically.

Human re-triage uses the repository's `scope-triage` skill. Review emoji
reactions, substantive comments, linked or duplicate requests, and reopening
history together. Automation flags qualifying comments and reopenings, but
GitHub Actions has no event for new reactions. Scheduled reaction polling and
stored baselines are deferred until repository activity justifies that added
machinery.

## Pull requests

Keep a pull request focused on one concern. Split unrelated UI polish, developer
tooling, or opportunistic cleanup into separate changes. A feature can fit the
constitution and still be declined if the implementation is unsafe, too broad,
or too expensive to maintain.

Describe any user-visible behaviour change in the pull request, including a
change that seems incidental to the main fix. Use `Closes #123` only when the
pull request resolves the outcome reported in that issue. A mitigation,
diagnostic improvement, or partial fix should use `Relates to #123` and leave the
original problem open.

Before submitting:

```bash
make lint

cd backend
venv/bin/python -m pytest

cd ../frontend
pnpm test
```

If your local environment differs, run the equivalent complete backend and
frontend suites and say exactly what you ran in the pull request. Compilation or
`py_compile` alone is not test evidence. Tests should assert the behaviour being
changed, not just that some output was produced.