Generation order seems reversed between design and spec

[zw-cyber]

This feels a bit odd. In actual generation, the design is produced first and the spec is generated afterward. However, the documentation indicates it should be spec first, then design. Additionally, the design output appears to be more detailed than the spec.

[1code-async]

Task completed.

Comment posted on issue #692. Here's a summary of the analysis:

Root cause: Both specs and design depend only on proposal, making them sibling nodes in the dependency graph. When both are ready, the tiebreaker in getBuildOrder() and getNextArtifacts() (graph.ts:109,133) uses alphabetical .sort(), placing "design" (d) before "specs" (s). The continue skill then picks the first ready artifact, so design is always generated first.

Key files involved:

• schemas/spec-driven/schema.yaml — defines the dependency graph
• src/core/artifact-graph/graph.ts:109,133 — alphabetical sort tiebreaker
• src/core/artifact-graph/instruction-loader.ts:352-354 — display ordering
• src/core/templates/skill-templates.ts:440 — "pick first ready" instruction

Related: Issue #674 (closed) where a maintainer stated there's no strict order between specs and design.

The comment suggests three potential fixes: update docs to match code, add a specs dependency to design, or use schema declaration order as the tiebreaker instead of alphabetical sort.

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Thanks for reporting this. The observation is correct — design is generated before specs at runtime, despite documentation showing proposal → specs → design → tasks.

Root Cause

Both specs and design only depend on proposal in the schema (schemas/spec-driven/schema.yaml:82-83 and schema.yaml:110-111), making them sibling nodes in the dependency graph:

                proposal
                   │
       ┌───────────┴───────────┐
       ▼                       ▼
     specs                   design
  (requires:              (requires:
   proposal)               proposal)
       │                       │
       └───────────┬───────────┘
                   ▼
                 tasks
            (requires:
            specs, design)

When both are ready simultaneously, the tie-breaking logic uses alphabetical sort:

• getBuildOrder() in src/core/artifact-graph/graph.ts:109 — queue.push(...newlyReady.sort()) places design (d) before specs (s)
• getNextArtifacts() in src/core/artifact-graph/graph.ts:133 — return ready.sort() also returns design first
• formatChangeStatus() in src/core/artifact-graph/instruction-loader.ts:352-354 sorts display output by getBuildOrder(), so design shows first
• The continue skill at src/core/templates/skill-templates.ts:440 says "Pick the FIRST artifact with status: 'ready'" → picks design

Result: The effective runtime order is proposal → design → specs → tasks, not proposal → specs → design → tasks as documented.

Regarding Design Being More Detailed Than Specs

The design artifact's instruction says to "Reference the proposal for motivation and specs for requirements" (schema.yaml:107), but when design is generated first, the specs don't exist yet. The LLM may compensate by including more detail in the design to fill the gap, which could explain why the design output appears more detailed than expected.

Related Issues

• Artifacts generation order #674 ("Artifacts generation order") — closed, with a maintainer clarifying that specs and design have no strict order and can be created either way. Both depend only on proposal.

Potential Fixes

There are a few options depending on the intended behavior:

1. If docs should match code (no strict order): Update documentation to clarify that specs and design are independent siblings and can be generated in either order, matching the maintainer's response in Artifacts generation order #674.

2. If code should match docs (specs before design): Change design to depend on specs in schema.yaml:

   - id: design
     requires:
       - proposal
       - specs    # enforce specs-first ordering

3. Preserve schema order instead of alphabetical sort: Modify getBuildOrder() and getNextArtifacts() in graph.ts to use the artifact's declaration order in schema.yaml as the tiebreaker instead of alphabetical sort. This would make the runtime order match the schema's listed order (specs is declared before design in the YAML).