Delta specs should be transformed when merging to not include "evolutionary" language

[marvingreenberg]

Title: Should spec sync strip change-oriented language from main specs?

---

During a recent change cycle (ux-refactor-simulate-tab), we noticed that
delta specs naturally use change-oriented language that makes sense in
context — things like:

- AND no separate Monte Carlo tab exists
- THEN the API receives the same Portfolio JSON structure as before
- AND no backend API changes are required

This reads fine in the delta spec (in changes/), where the purpose is to
describe what changed. But when these deltas get synced to main specs
(via /opsx:sync or /opsx:archive), that language ends up in the
permanent spec, where it reads oddly. A main spec is supposed to describe
the current system — "what IS" — and saying "no Monte Carlo tab exists"
is a strange thing to assert as a permanent requirement. Taken to its
logical conclusion, main specs would accumulate lots of negations about
things that used to exist.

After the sync, we manually rewrote the affected scenarios:

Before (change language):
- THEN the tab navigation shows "Portfolio", "Simulate", and "Compare"
- AND no "Monte Carlo" tab exists

After (describes what IS):
- THEN the tab navigation shows exactly 3 tabs: "Portfolio", "Simulate", and "Compare"

Before:
- THEN the API receives the same Portfolio JSON structure as before
- AND no backend API changes are required

After:
- THEN the API receives a single Portfolio JSON containing both
  portfolio data and simulation assumptions

The archived delta specs still preserve the evolutionary context for
anyone who wants to understand what changed and why.

---

Possible approaches:

1. Add guidance to the /opsx:sync and /opsx:archive skill prompts

   The sync/archive logic is where deltas get merged into main specs.
   Adding a step like "rewrite content to describe current system state,
   strip change-oriented language" would catch this at the right point
   in the workflow. This seems like the most natural fit since:

   • Delta spec authors SHOULD use change language (that's the point of
     ADDED/MODIFIED/REMOVED headers)
   • The transformation should happen at sync time, not authoring time
   • It's a universal principle, not project-specific

2. Add guidance to the specs artifact instruction template

   The instruction field for the specs artifact could mention that
   scenario content should be written to stand on its own, even in
   delta specs. But this conflicts with the delta format — MODIFIED
   specs inherently reference what changed.

3. Per-project rules in config.yaml

   Projects can add a rule like:
   rules:
   specs:
   - Main specs describe what IS, not what changed. Strip
   evolutionary language during sync.

   This works but puts the burden on each project to discover and
   configure this. It also lands in the spec authoring instructions,
   not the sync step where it matters.

Approach 1 seems like the best fit — it's where the transformation
naturally belongs, and it would benefit all openspec users without
requiring per-project configuration.

attribution - Claude Opus 4.5, in openspec --version 1.1.1

[1code-async]

Task completed.

The enrichment comment has been posted on issue #678. Here's a summary of what it covers:

Key findings:

1. Not a duplicate — no existing issues cover this topic. question: why achive skill or command relies on llm to manually merge specs why it does not use openspec archive cli command? #656 is the closest but addresses a different concern (why archive uses LLM merging at all).

2. Mapped all three approaches to specific code locations with file paths and line numbers:

   • Approach 1 (sync/archive skill prompts) → src/core/templates/skill-templates.ts:2474-2608
   • Approach 2 (specs instruction template) → schemas/spec-driven/schema.yaml:30-82
   • Approach 3 (config rules) → src/core/project-config.ts

3. Identified an important architectural gap — there are two separate sync paths (agent-driven via /opsx:sync and programmatic via openspec archive CLI). Approach 1 only covers the agent-driven path. The CLI path does structural block manipulation without semantic understanding, so it can't detect or rewrite evolutionary language without an LLM call.

4. Provided a concrete implementation suggestion — specific text to add to the sync skill prompt under the existing "Key Principle" section, plus a note about updating the formal spec.

---

View full conversation

Powered by 1Code

[marvingreenberg]

I raised this issue with the chatbot since the merged specs seemed unnatural to me. This issue above was generated from the conversation about that.

[1code-async]

Issue Analysis

Not a duplicate

No existing issues cover this topic. The closest related issue is #656 (why archive relies on LLM for merging), which touches on the same sync/archive workflow but addresses a different concern.

Relevant code locations

The three approaches map to these files:

Approach 1 — Modify /opsx:sync and /opsx:archive skill prompts (recommended by author)

The skill prompt templates are defined in:

• /opsx:sync skill: src/core/templates/skill-templates.ts:2474-2608 — getOpsxSyncCommandTemplate(). The sync skill is agent-driven (the LLM reads delta specs and edits main specs directly). This is where transformation guidance would be most effective. The "Key Principle: Intelligent Merging" section at line 2576 already establishes the pattern of the agent using judgment during merging — adding "rewrite change-oriented language to describe current system state" fits naturally here.

• /opsx:archive skill: src/core/templates/skill-templates.ts:2784-2941 — getOpsxArchiveCommandTemplate(). The archive skill delegates sync to the sync skill (line 2844), so adding guidance here would be redundant if approach 1 focuses on /opsx:sync.

• Formal spec for sync skill: openspec/specs/specs-sync-skill/spec.md — Would need a new scenario under "Delta Reconciliation Logic" describing the language transformation requirement.

Approach 2 — Modify specs artifact instruction template

• Schema definition: schemas/spec-driven/schema.yaml:30-82 — The specs artifact's instruction field. As the issue notes, this conflicts with delta spec intent — delta authors should use change-oriented language since the format uses ADDED/MODIFIED/REMOVED headers.

Approach 3 — Per-project rules in config.yaml

• Config schema: src/core/project-config.ts — The rules field is a Record<string, string[]> keyed by artifact ID. Rules get injected into artifact instructions wrapped in <rules> tags (see src/core/artifact-graph/instruction-loader.ts). As the issue notes, rules target authoring-time instructions, not sync-time behavior — making this approach a poor fit.

Important architectural context

There are two separate sync paths — this matters for implementation:

1. Agent-driven sync (/opsx:sync skill) — The LLM reads delta specs and directly edits main specs. This is where Approach 1 would apply and is the natural place for language transformation since the agent is already making judgment calls about how to merge content.

2. Programmatic sync (openspec archive CLI command) — Uses src/core/specs-apply.ts and src/core/archive.ts for structural merging (add/modify/remove/rename requirement blocks). This path performs text-level block manipulation without semantic understanding — it wouldn't be able to detect or rewrite "evolutionary language" without an LLM call.

This means Approach 1 only covers the agent-driven path. Users who run openspec archive from the CLI get programmatic merging that copies delta content verbatim. Addressing the CLI path would require either:

• Calling an LLM during openspec archive (significant architectural change, relates to question: why achive skill or command relies on llm to manually merge specs why it does not use openspec archive cli command? #656)
• Accepting that CLI archive is a structural merge and language cleanup is a manual step

Suggested implementation for Approach 1

Add a new guideline to the /opsx:sync skill prompt in getOpsxSyncCommandTemplate(), under the existing "Key Principle" section at line 2576:

**Key Principle: Main Specs Describe Current State**

When writing content to main specs, rewrite any change-oriented or evolutionary 
language from the delta to describe the current system state. Delta specs describe 
what CHANGED — main specs describe what IS.

Examples of transformations:
- "no Monte Carlo tab exists" → list the tabs that DO exist
- "the API receives the same structure as before" → describe the actual structure
- "no backend API changes are required" → (omit — this is only meaningful in context of a change)

The archived delta specs preserve the evolutionary context for anyone who needs it.

A corresponding new scenario should be added to openspec/specs/specs-sync-skill/spec.md under the "Delta Reconciliation Logic" requirement.