Skip to content
ttorta docs

Troubleshooting

Tickets the linter refuses

The filename rule, the missing frontmatter fields, and the section budgets.

lint-ticket.py checks tickets against the same torta.json the board and the engine read.

The filename is wrong

filename must be <type>.<three-word-name>.<STATUS>.md, all lowercase except the status — the assignee belongs in frontmatter, not here

So feature.add-empty-state.REVIEW.md passes. The type is one of feature, fix, chore, refactor, adhoc, epic or hotfix.

frontmatter missing <field>:

Eight fields are required on every ticket: status, project, type, title, assignee, author, date and repo. There is also frontmatter missing redo_count: (starts at 0).

Two more have their own messages:

  • frontmatter missing ticket: — every ticket is numbered at creation
  • frontmatter missing epic: — every ticket names the open sprint

a feature ticket must have ## Acceptance criteria

A feature needs, in order, User story, Acceptance criteria, Motivation, Proposed change, Impact and risks and Verification. The full table is in the workflow schema.

## Proposed change uses 41 non-blank lines, budget is 25

Each section has a line budget. Trim it, or raise the budget in torta.json under workflow.budgets. A whole ticket is also capped at 300 non-blank lines, with ## History excluded.

Status and hierarchy findings

  • an epic is OPEN or CLOSED, never WIP
  • OPEN belongs to an epic — a feature cannot take it
  • an epic does not carry epic: — it is the epic
  • parent: names this ticket — a ticket cannot be its own parent
  • children: names this ticket — a parent cannot be its own child

unknownStatuses on the board

GET /api/state reports unknownStatuses for any status present on disk that the workflow legend does not name, usually a ticket renamed by hand.

Where the rules live

Every rule on this page is read from workflow in torta.json. After changing it, regenerate:

torta sync