unic / unic/unic-agents-plugins

Rewrite commands/tickets.md from scratch against the to-tickets Method

Open
#382 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

app:unic-archon-dlc p2 wayfinder:grilling
Dominant language
JavaScript
Stars
1
Forks
0
Avg merge
16h 43m
Merged PRs (30d)
19

Description

Question

Rewrite commands/tickets.md from scratch, against the to-tickets Method.

Today it is 357 lines against the Method's 105. It reads the Method by path, so it composes — and then
restates the Method's field list, its presentation format and its publishing step, and invents a
"PRD coverage" rule the Method deliberately does not ask for. Decision 12 says rewrite, not trim,
because the frustration should leave a worked example behind.

The Harness owns: config load, target-repository derivation, slug and re-entry, the test seam per
slice, issues.json as the durable baton, and the gate. The Method owns everything about how to
slice. Nothing in the command may paraphrase, summarise or improve the Method.

issues.json carrying the tracker id of each published ticket is part of what the Harness owns
here. #389 puts that rule in the file first
and lands well before this ticket; the rewrite preserves it rather than re-deciding it.

This becomes the pattern for specs.md (323), improve-architecture.md (285) and triage.md (201).
Get it right once.

Acceptance criteria

  • tickets.md is rewritten, and every paragraph in it is something the Method does not say.
  • The Method's field list, presentation format and publishing step appear nowhere in the command.
  • The "PRD coverage" rule is gone.
  • No plugin module is imported; config and the Method are read by path.
  • The command still produces a dependency-ordered issues.json and publishes to the configured
    tracker, proven by a run.
  • A slice that a design contract belongs to carries that contract's path in the body it publishes, and
    the command says so itself rather than leaving it to the operator's eye.
  • A slice can carry a criterion that another slice deferred to it, and the command asks for those rather
    than relying on someone remembering a pull-request thread.
  • The command either sets a published item's parent, or states in one line that it does not and that the
    operator sets it — silence on the point is what produced a flat backlog on the first real run.
  • The two dead-module citations are gone: sortByDependency at line 179 and validateIssue at line 182,
    both naming modules #381 deleted.

What the first real run measured — amended 2026-08-26 by the orchestrator

wayfinder-379 ran the current commands/tickets.md against DXP-DesignSystem while working
#379. Three gaps showed up, each one costing a
by-hand check at the Step 10 gate that the command should have owned. They are the four criteria above, and
they are recorded here because a gap measured on a real run and then forgotten is worse than one nobody has
found: the workaround becomes the convention.

  1. The command does not know design contracts exist. Grepped 2026-08-26 on develop:
    contract.generated, figma and design contract appear nowhere in the file.
    #416 wrote the /specs half of
    contract-carrying — "a preparation slice carries the contract path too, or the work it exists to unblock
    starts blind"
    — and nothing carried it here. So the operator verifies each slice's contract path by eye.
  2. A deferral has nowhere to live. The prefactor answered two review findings with "not yet, and here is
    why" — passWithNoTests in the Storybook vitest config, and a tsconfig paths mapping serving an
    add-then-reshape window. Both are correct answers with an expiry date, and the only home the run had for
    them was a pull-request thread, which expires when the thread scrolls. They had to be hand-carried into
    the next slice's acceptance criteria by a human holding them in mind.
  3. The command sets no parent. Step 9 writes the acceptance criteria, the blocked-by references and the
    state role, and nothing else, so published slices sit flat. On the first run a parent Feature
    (WI 42975) had to be created separately and each
    slice parented by hand. Either the command owns it or it says plainly that it does not; what it must not
    do is leave the reader to discover it.

A note on the fourth criterion, so the rewrite does not treat it as trivia: those two citations point at
modules that no longer exist, so an agent reading the file looks for code it will never find. The line
numbers are correct as measured on develop at 348f231 — and both #416's close-out and an orchestrator
handoff previously cited line 174, which was wrong. Re-grep before trusting either number.


Added 2026-08-29 — the rewrite should give /tickets a parent it can set

Raised by the maintainer while planning a second /specs/tickets/build run at FZAG.

Today /tickets publishes one item per slice and sets no parent. Line 236 of the current
commands/tickets.md says "Do NOT close or modify any parent item", and nothing creates one. So a
human parents every slice by hand after every run. That is what happened on the first real run, and it
worked because one person remembered.

The values are tenant facts and must stay out of this plugin. On the FZAG board a feature is a
User Story and a slice is a Task, and both are Azure DevOps concepts. CONTEXT.md's rule holds:
a Box names a role and a file, never an organisation, a field or a provider. The Consumer is recording
its own shape in docs/agents/issue-tracker.md under
WI 42998, as a tenant fact.

What is missing here is the capability, not the values. A written convention in a Consumer's tracker
contract has no reader today: /tickets has no step that sets a parent, and triage-labels.md's
three tiers — state, type, priority — carry no hierarchy. So the Consumer can state the shape perfectly
and nothing will act on it.

Suggested scope for the rewrite, deliberately minimal:

  1. /tickets reads a parent from the tracker contract if one is named, and sets each published item's
    parent to it. It does not learn what a "User Story" is.
  2. The contract gains one way to name that parent. Whether that is a new section in issue-tracker.md,
    a role in triage-labels.md, or a /tickets argument is this issue's to decide — note that a role
    in triage-labels.md would be the fourth tier and the file is explicitly three
    .
  3. If nothing names a parent, behaviour is unchanged: publish flat, set nothing. A Consumer that does not
    want hierarchy must not acquire one.

One check for whoever takes it, because this issue's own body is a rewrite plan and the trap is
symmetrical: ask which part of the new tickets.md a Consumer could satisfy by writing prose that nothing
reads. That is the defect being fixed here, and a rewrite can reintroduce it in a new place.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with commands/tickets.md and docs/agents/issue-tracker.md, then trace how the command reads configuration and the Method and produces issues.json. Decide how the tracker contract names a parent, preserve tracker IDs and design-contract and deferred-criterion handling, and prove completion with a real run that publishes dependency-ordered tickets without the obsolete citations.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
cli, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.