Skip to content

Commit e97c53c

Browse files
remarkablemarkremarkablemark
committed
docs(qwen): migrate from toml to md
1 parent 024fc2b commit e97c53c

11 files changed

Lines changed: 526 additions & 511 deletions

.qwen/commands/speckit.analyze.toml renamed to .qwen/commands/speckit.analyze.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
description = "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
2-
3-
prompt = """
41
---
52
description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
63
---
74

5+
---
6+
7+
## description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
8+
89
## User Input
910

1011
```text
@@ -34,7 +35,7 @@ Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --inclu
3435
- TASKS = FEATURE_DIR/tasks.md
3536

3637
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
37-
For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
38+
For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
3839

3940
### 2. Load Artifacts (Progressive Disclosure)
4041

@@ -129,16 +130,16 @@ Output a Markdown report (no file writes) with the following structure:
129130

130131
## Specification Analysis Report
131132

132-
| ID | Category | Severity | Location(s) | Summary | Recommendation |
133-
|----|----------|----------|-------------|---------|----------------|
134-
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
133+
| ID | Category | Severity | Location(s) | Summary | Recommendation |
134+
| --- | ----------- | -------- | ---------------- | ---------------------------- | ------------------------------------ |
135+
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
135136

136137
(Add one row per finding; generate stable IDs prefixed by category initial.)
137138

138139
**Coverage Summary Table:**
139140

140141
| Requirement Key | Has Task? | Task IDs | Notes |
141-
|-----------------|-----------|----------|-------|
142+
| --------------- | --------- | -------- | ----- |
142143

143144
**Constitution Alignment Issues:** (if any)
144145

@@ -185,4 +186,3 @@ Ask the user: "Would you like me to suggest concrete remediation edits for the t
185186
## Context
186187

187188
{{args}}
188-
"""

.qwen/commands/speckit.checklist.toml renamed to .qwen/commands/speckit.checklist.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
description = "Generate a custom checklist for the current feature based on user requirements."
2-
3-
prompt = """
41
---
52
description: Generate a custom checklist for the current feature based on user requirements.
63
---
74

5+
---
6+
7+
## description: Generate a custom checklist for the current feature based on user requirements.
8+
89
## Checklist Purpose: "Unit Tests for English"
910

1011
**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
@@ -38,7 +39,7 @@ You **MUST** consider the user input before proceeding (if not empty).
3839

3940
1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
4041
- All file paths must be absolute.
41-
- For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
42+
- For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
4243

4344
2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
4445
- Be generated from the user's phrasing + extracted signals from spec/plan/tasks
@@ -296,4 +297,3 @@ Sample items:
296297
- Correct: Validation of requirement quality
297298
- Wrong: "Does it do X?"
298299
- Correct: "Is X clearly specified?"
299-
"""

‎.qwen/commands/speckit.clarify.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
3+
---
4+
5+
---
6+
7+
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
8+
handoffs:
9+
10+
- label: Build Technical Plan
11+
agent: speckit.plan
12+
prompt: Create a plan for the spec. I am building with...
13+
14+
---
15+
16+
## User Input
17+
18+
```text
19+
$ARGUMENTS
20+
```
21+
22+
You **MUST** consider the user input before proceeding (if not empty).
23+
24+
## Outline
25+
26+
Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
27+
28+
Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
29+
30+
Execution steps:
31+
32+
1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
33+
- `FEATURE_DIR`
34+
- `FEATURE_SPEC`
35+
- (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
36+
- If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
37+
- For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
38+
39+
2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
40+
41+
Functional Scope & Behavior:
42+
- Core user goals & success criteria
43+
- Explicit out-of-scope declarations
44+
- User roles / personas differentiation
45+
46+
Domain & Data Model:
47+
- Entities, attributes, relationships
48+
- Identity & uniqueness rules
49+
- Lifecycle/state transitions
50+
- Data volume / scale assumptions
51+
52+
Interaction & UX Flow:
53+
- Critical user journeys / sequences
54+
- Error/empty/loading states
55+
- Accessibility or localization notes
56+
57+
Non-Functional Quality Attributes:
58+
- Performance (latency, throughput targets)
59+
- Scalability (horizontal/vertical, limits)
60+
- Reliability & availability (uptime, recovery expectations)
61+
- Observability (logging, metrics, tracing signals)
62+
- Security & privacy (authN/Z, data protection, threat assumptions)
63+
- Compliance / regulatory constraints (if any)
64+
65+
Integration & External Dependencies:
66+
- External services/APIs and failure modes
67+
- Data import/export formats
68+
- Protocol/versioning assumptions
69+
70+
Edge Cases & Failure Handling:
71+
- Negative scenarios
72+
- Rate limiting / throttling
73+
- Conflict resolution (e.g., concurrent edits)
74+
75+
Constraints & Tradeoffs:
76+
- Technical constraints (language, storage, hosting)
77+
- Explicit tradeoffs or rejected alternatives
78+
79+
Terminology & Consistency:
80+
- Canonical glossary terms
81+
- Avoided synonyms / deprecated terms
82+
83+
Completion Signals:
84+
- Acceptance criteria testability
85+
- Measurable Definition of Done style indicators
86+
87+
Misc / Placeholders:
88+
- TODO markers / unresolved decisions
89+
- Ambiguous adjectives ("robust", "intuitive") lacking quantification
90+
91+
For each category with Partial or Missing status, add a candidate question opportunity unless:
92+
- Clarification would not materially change implementation or validation strategy
93+
- Information is better deferred to planning phase (note internally)
94+
95+
3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
96+
- Maximum of 5 total questions across the whole session.
97+
- Each question must be answerable with EITHER:
98+
- A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
99+
- A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
100+
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
101+
- Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
102+
- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
103+
- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
104+
- If more than 5 categories remain unresolved, select the top 5 by (Impact \* Uncertainty) heuristic.
105+
106+
4. Sequential questioning loop (interactive):
107+
- Present EXACTLY ONE question at a time.
108+
- For multiple‑choice questions:
109+
- **Analyze all options** and determine the **most suitable option** based on:
110+
- Best practices for the project type
111+
- Common patterns in similar implementations
112+
- Risk reduction (security, performance, maintainability)
113+
- Alignment with any explicit project goals or constraints visible in the spec
114+
- Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
115+
- Format as: `**Recommended:** Option [X] - <reasoning>`
116+
- Then render all options as a Markdown table:
117+
118+
| Option | Description |
119+
| ------ | --------------------------------------------------------------------------------------------------- |
120+
| A | <Option A description> |
121+
| B | <Option B description> |
122+
| C | <Option C description> (add D/E as needed up to 5) |
123+
| Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
124+
- After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
125+
126+
- For short‑answer style (no meaningful discrete options):
127+
- Provide your **suggested answer** based on best practices and context.
128+
- Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
129+
- Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
130+
- After the user answers:
131+
- If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
132+
- Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
133+
- If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
134+
- Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
135+
- Stop asking further questions when:
136+
- All critical ambiguities resolved early (remaining queued items become unnecessary), OR
137+
- User signals completion ("done", "good", "no more"), OR
138+
- You reach 5 asked questions.
139+
- Never reveal future queued questions in advance.
140+
- If no valid questions exist at start, immediately report no critical ambiguities.
141+
142+
5. Integration after EACH accepted answer (incremental update approach):
143+
- Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
144+
- For the first integrated answer in this session:
145+
- Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
146+
- Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
147+
- Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
148+
- Then immediately apply the clarification to the most appropriate section(s):
149+
- Functional ambiguity → Update or add a bullet in Functional Requirements.
150+
- User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
151+
- Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
152+
- Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
153+
- Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
154+
- Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
155+
- If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
156+
- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
157+
- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
158+
- Keep each inserted clarification minimal and testable (avoid narrative drift).
159+
160+
6. Validation (performed after EACH write plus final pass):
161+
- Clarifications session contains exactly one bullet per accepted answer (no duplicates).
162+
- Total asked (accepted) questions ≤ 5.
163+
- Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
164+
- No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
165+
- Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
166+
- Terminology consistency: same canonical term used across all updated sections.
167+
168+
7. Write the updated spec back to `FEATURE_SPEC`.
169+
170+
8. Report completion (after questioning loop ends or early termination):
171+
- Number of questions asked & answered.
172+
- Path to updated spec.
173+
- Sections touched (list names).
174+
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
175+
- If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
176+
- Suggested next command.
177+
178+
Behavior rules:
179+
180+
- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
181+
- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
182+
- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
183+
- Avoid speculative tech stack questions unless the absence blocks functional clarity.
184+
- Respect user early termination signals ("stop", "done", "proceed").
185+
- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
186+
- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
187+
188+
Context for prioritization: {{args}}

0 commit comments

Comments
 (0)