unic / unic/unic-agents-plugins

Decide what a design blocking condition costs the rest of a /specs run

Open
#429 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

app:unic-archon-dlc feature needs-specs p3
Dominant language
JavaScript
Stars
1
Forks
0
Avg merge
16h 43m
Merged PRs (30d)
19

Description

What surfaced

#404 decided that a design-conventions doc may declare blocking conditions and that they stop /specs. It decided nothing about what a block costs the rest of the run, and #416 had to answer that to make the prose executable.

What commands/specs.md now says, marked in the file as this command's rule rather than the doc's:

  • No contract for the component that blocked. Never a partial or empty one — an empty contract reads as a component with no properties, not as one nobody could read.
  • No contract for the components after it either.
  • Print the Step 9 summary with the blocked: line filled and gate: not opened, then stop before the gate.
  • Contracts already written this run stay on disk unstaged, and the summary lists them as written-not-staged. The PRD stays on disk, and Step 2 picks it up as a re-entry.

The decision

Fail-fast on the whole set, or write every contract that can be written and report the blocked ones at the gate? The trade is visible: fail-fast never puts a half-set in front of a human, and write-what-you-can keeps a nine-component feature moving when one component is untidy in the design file.

The current answer is fail-fast, chosen because a partial set reaching the gate is the shape a human approves without noticing. Whoever reverses it owns the summary line that makes a partial set legible.

Evidence for either side

Measured 2026-08-25 on the Consumer (#403, #405): focus is drawn nowhere on all four interactive sets and three typos stand, so the first real run blocks on the first component it reads. That makes fail-fast indistinguishable from write-what-you-can today, and the difference only appears once the design side is clean.

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/specs.md, especially the blocking-condition rule and Step 9 summary, then read issues #404 and #416 for the existing decisions. Compare fail-fast with write-what-you-can against the Consumer evidence in #403 and #405; done means the chosen policy and its summary behavior are unambiguous and recorded.

Written by the indexing model from the issue text.

Assessment

Domain
cli, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.