Incomplete specs after proposal

[gabinoguera]

En features imporantes, utilizando CLAUDE.md los specs no llegan a reflejar exhaustivamente lo que se ha planificado en proposal y design. Me he encontrado con esto:

• /opsx:ff genera artefactos rápido pero no tiene un paso de cross-reference
  contra el documento fuente
• /opsx:verify existe pero es para post-implementación (verifica código vs
  specs), no para verificar specs vs proposal
• No hay nada que valide que los specs cubran exhaustivamente el proposal

Las features quedan reflejadas a medias tanto en los specs como en las task. Mi solucion fue implementar un nuevo SKILL:

Nuevo skill /opsx:audit

• Lanza 2 agentes en paralelo: técnico (componentes, data model, shortcuts,
  fases) + UX/UI (estados, cursores, toolbar, feedback visual)
  • Cross-reference exhaustivo contra proposal y docs de referencia
  • Checklist de 15 categorías (componentes, hooks, data fields, shortcuts, UI
    states, cursors, toolbar controls, context menu, visual feedback, interaction
    flows, performance, backward-compat, phases, dependencies, design decisions)
  • Produce reporte: GAPS / PARTIAL / COVERED
  • Ofrece auto-fix si se encuentran gaps
  • Invocable manualmente: /opsx:audit <nombre_spec>

[21st-connector]

Task completed.

The enrichment comment has been posted on issue #687. Here's a summary of what was included:

Problem validation: Confirmed the gap is real — no existing skill performs upstream validation (specs ← proposal). /opsx:ff creates artifacts sequentially without cross-referencing, and /opsx:verify only validates code against specs post-implementation.

Code locations: Linked to the specific files and line numbers for /opsx:ff (skill-templates.ts:674-772), /opsx:verify (skill-templates.ts:2614-2778), and the registration points in skill-generation.ts.

Implementation path: Documented the 5-step process to add a new /opsx:audit skill following the same pattern used for the verify skill.

Related issues: Identified #431 (Richer Spec Validation) and #381 (Lightweight verification step) as the most closely related — none are duplicates.

Design considerations: Raised 4 points for discussion — whether this should be a separate skill vs. a flag on /opsx:ff, how to relate it to /opsx:verify, whether multi-agent is necessary, and whether the 15-category checklist should be configurable.

---

View full conversation

Powered by 1Code

[21st-connector]

Issue Triage: Codebase Analysis

Problem Summary

The issue identifies a gap in the OpenSpec artifact pipeline: there is no validation step between proposal → specs to ensure specs exhaustively reflect the proposal. The existing workflow has:

• /opsx:ff — creates all artifacts sequentially but without cross-referencing specs back against the proposal (src/core/templates/skill-templates.ts:674-772)
• /opsx:verify — validates code vs. specs/tasks/design (post-implementation), not specs vs. proposal (src/core/templates/skill-templates.ts:2614-2778)

The gap is real: no existing skill performs upstream validation (specs ← proposal).

Relevant Code Locations

File	Lines	What It Does
src/core/templates/skill-templates.ts	674-772	/opsx:ff skill — fast-forwards artifact creation, no cross-reference step
src/core/templates/skill-templates.ts	2614-2778	/opsx:verify skill — verifies implementation against specs/tasks/design
src/core/shared/skill-generation.ts	51-63	Skill template registry — where new skills are registered
src/core/shared/skill-generation.ts	69-82	Command template registry — where new /opsx:* commands are registered
src/core/shared/tool-detection.ts	—	SKILL_NAMES array — needs entry for any new skill
schemas/spec-driven/schema.yaml	—	Artifact dependency graph (proposal → specs → design → tasks)

How to Add a New Skill (Implementation Path)

Based on the existing pattern (e.g., how verify was added), a new /opsx:audit skill would require:

1. Add template function in src/core/templates/skill-templates.ts:

   • getAuditChangeSkillTemplate(): SkillTemplate — skill definition with instructions
   • getOpsxAuditCommandTemplate(): CommandTemplate — slash command definition

2. Register in src/core/shared/skill-generation.ts:

   • Add to getSkillTemplates() array (~line 52): { template: getAuditChangeSkillTemplate(), dirName: 'openspec-audit-change' }
   • Add to getCommandTemplates() array (~line 70): { template: getOpsxAuditCommandTemplate(), id: 'audit' }

3. Register in src/core/shared/tool-detection.ts:

   • Add 'openspec-audit-change' to SKILL_NAMES

4. Export from src/core/templates/index.ts

5. Run openspec update to generate the skill/command files for all configured AI tools (22 adapters auto-generate tool-specific command files).

Related Issues

• Richer Spec Validation & Tooling #431 — Richer Spec Validation & Tooling — Most closely related; requests better spec validation tooling
• Add lightweight verification step (implementation vs spec) #381 — Add lightweight verification step (implementation vs spec) — Led to the current /opsx:verify skill; same pattern could be followed for spec-vs-proposal
• [Proposal] Add hierarchical spec structure support #662 — Hierarchical spec structure support — Structural spec improvements
• How to update specifications during the apply phase? #684 — How to update specifications during apply phase — Spec lifecycle question
• /openspec:proposal Generates Non-Standard proposal.md #490 — Proposal generates non-standard proposal.md — Proposal generation quality

None of these are exact duplicates. This issue proposes a distinct upstream validation step (specs ← proposal) that doesn't exist in any form today.

Design Considerations

1. Scope of /opsx:ff vs. new skill: An alternative to a separate /opsx:audit skill would be adding an optional cross-reference step within /opsx:ff itself (e.g., a --verify flag or an automatic post-generation check). This would catch gaps at generation time rather than requiring a separate invocation.

2. Relationship with /opsx:verify: The proposed audit skill covers a different direction (upstream: specs ← proposal) vs. verify (downstream: code ← specs). Consider whether both could share a common verification framework or report format for consistency.

3. Parallel agents: The proposal suggests launching 2 agents (technical + UX/UI). The existing skill system uses single-agent execution. Multi-agent coordination would be a new pattern — consider whether a single-agent sequential approach with two passes could achieve similar results with less complexity.

4. 15-category checklist: The hardcoded category list (components, hooks, data fields, shortcuts, UI states, cursors, toolbar controls, context menu, visual feedback, interaction flows, performance, backward-compat, phases, dependencies, design decisions) is highly specific. Consider making categories configurable via openspec/config.yaml to keep the skill generic across different project types.