docs: add OPSX experimental workflow visibility to README #460
Conversation
Add a subtle banner near the top and an Experimental Features section before Contributing to draw attention to the new OPSX workflow.
📝 WalkthroughWalkthroughAdded and expanded documentation for the OPSX experimental workflow: a centered README banner, an "Experimental Features" collapsible block duplicated under "Updating OpenSpec", and a comprehensive rewrite of Changes
Sequence Diagram(s)(omitted — documentation-only changes; no new runtime control flow introduced) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
README.md (1)
382-384: Fix: Add language specification to fenced code block (MD040).Specifying a language improves content rendering by using the correct syntax highlighting for code. The workflow diagram block on line 382 should specify a language identifier.
🔧 Proposed fix
-``` +```text proposal → specs → design → tasks → implementation → archive -``` +```Alternatively, use
plaintextif preferred. This resolves the markdownlint MD040 rule violation.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md
🧰 Additional context used
🧠 Learnings (5)
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
README.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
README.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
README.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
README.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
README.md
🪛 markdownlint-cli2 (0.18.1)
README.md
382-382: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
README.md (2)
29-31: Approve: Subtle and well-placed banner.The positioning after the header badges and before the main content is appropriate for visibility without intrusiveness. The messaging clearly indicates this is experimental.
Verify that the referenced file
docs/experimental-workflow.mdexists at the repository root relative to README.md. If this file is included in the same PR, confirm the path resolves correctly.
375-398: Approve: Well-structured experimental features section with clear workflow.The collapsible section effectively introduces OPSX without cluttering the main README. The command table is clear, setup instructions are concise, and the link to full documentation provides an escape hatch for users who want deeper information. The "Claude Code only" qualifier is appropriately highlighted.
Per the AI-generated summary, duplication of this section was mentioned as occurring under the "Updating OpenSpec" area. However, the provided code shows only one "Experimental Features" section (lines 375-398). Clarify whether the duplication is intentional or if it should be removed from another location.
Update messaging to emphasize the core value proposition: - No phases, just actions - Dependencies are enablers, not gates - Update artifacts as you learn during implementation The previous "step-by-step artifact creation" framing incorrectly suggested more bureaucracy. OPSX is about less rigidity, not more.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
README.md (1)
384-390: Add language specifier to code fence.The ASCII workflow diagram is helpful, but the fenced code block should include a language specifier for linting compliance.
📝 Proposed fix
-``` +```text You can always go back:docs/experimental-workflow.md (1)
63-84: Add language specifiers to code fences for linting compliance.Multiple code blocks in the usage section lack language specifiers, which triggers markdown linting violations. These appear to be bash/command examples and should be marked accordingly.
📝 Proposed fixes
### Create artifacts -``` +```bash /opsx:continue -``` +```-/opsx:ff add-dark-mode
-+bash
+/opsx:ff add-dark-mode
+```Implement (the fluid part)
-
+bash
/opsx:apply
-+Finish up
-
+bash
/opsx:sync # Update main specs with your delta specs
/opsx:archive # Move to archive when done
-+</details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 10e91cf77e2d37a7c1fd037f1ed79c956be347dc and 12ef8ef3578d03c9f1ca20faa156ccd10ffd4101. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `README.md` * `docs/experimental-workflow.md` </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (10)</summary> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal usingproposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/**Applied to files:** - `docs/experimental-workflow.md` - `README.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensureproposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)**Applied to files:** - `docs/experimental-workflow.md` - `README.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:02.839Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use@/openspec/AGENTS.mdto learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines**Applied to files:** - `docs/experimental-workflow.md` - `README.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:02.839Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open@/openspec/AGENTS.mdwhen the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding**Applied to files:** - `docs/experimental-workflow.md` - `README.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes//specs//spec.md : Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files**Applied to files:** - `docs/experimental-workflow.md` - `README.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes//specs//spec.md : Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements**Applied to files:** - `docs/experimental-workflow.md` - `README.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Useopenspec archive <change-id> --skip-specs --yesfor tooling-only changes**Applied to files:** - `docs/experimental-workflow.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Checkopenspec/project.mdfor project conventions before creating specs**Applied to files:** - `docs/experimental-workflow.md` - `README.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensuretasks.mdcontains implementation checklist with numbered sections and checkbox items**Applied to files:** - `docs/experimental-workflow.md` </details> <details> <summary>📚 Learning: 2025-11-25T01:08:19.004Z</summary>Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Createdesign.mdonly when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity**Applied to files:** - `README.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>docs/experimental-workflow.md</summary> 19-19: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 64-64: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 69-69: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 75-75: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 81-81: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> <details> <summary>README.md</summary> 384-384: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>🔇 Additional comments (7)</summary><blockquote> <details> <summary>README.md (2)</summary><blockquote> `29-31`: **Banner placement and messaging are effective.** The experimental workflow banner is well-positioned after the logo section and clearly signals the new feature without overwhelming the main content. The link to `docs/experimental-workflow.md` should resolve correctly. --- `375-404`: **Experimental Features section is well-structured and clearly presented.** The collapsible block effectively introduces OPSX with a clear problem statement, workflow diagram, and actionable commands. The structure mirrors the existing "Native Slash Commands" section, maintaining consistency. The link to full documentation appropriately guides power users. </blockquote></details> <details> <summary>docs/experimental-workflow.md (5)</summary><blockquote> `1-30`: **OPSX workflow reframing is clear and well-justified.** The problem statement (lines 11–12) effectively articulates why linear phases fail in practice. The three-bullet OPSX approach (lines 14–17) clearly positions actions, enablers, and iterative updates as core values. The workflow diagram with backtracking effectively visualizes the non-linear capability. --- `44-84`: **Commands and usage sections are clear with good practical examples.** The subsection headers ("Create artifacts", "Implement (the fluid part)", "Finish up") add helpful context, and the key difference note (line 78) effectively reinforces the no-phase-gates philosophy. Examples like `add-dark-mode` are concrete and relatable. --- `86-95`: **Comparison table effectively differentiates workflows.** The four-row table clearly shows how OPSX differs from the standard workflow across structure, iteration patterns, and customization. The "Key insight" statement (line 95) provides a strong philosophical anchor. The inclusion of schema-driven customization hints at future extensibility. --- `106-117`: **Tips and feedback sections are appropriately candid and helpful.** The guidance on when to use `/opsx:ff` vs. `/opsx:continue` (line 108) and the explicit encouragement to fix artifacts mid-work (line 109) effectively reinforce the fluid iteration philosophy. The honest feedback statement and community links appropriately position this as experimental and actively evolving. --- `1-1`: **Verify completeness of README duplication mentioned in AI summary.** The AI summary indicates that "Experimental Features" content was duplicated under the "Updating OpenSpec" section, but the provided README code shows only one instance (lines 375–404, before Contributing). Please confirm whether this duplication is intended and whether it appears in the full PR diff. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Add comprehensive comparison of standard vs OPSX workflow architecture: - Philosophy: phases vs actions - Component architecture diagrams - Dependency graph model - Information flow comparison - Iteration model comparison - Custom schema example
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @docs/experimental-workflow.md:
- Around line 19-30: The fenced code blocks in docs/experimental-workflow.md are
missing language identifiers (MD040); update each triple-backtick block to
include an appropriate language tag: use "text" or "ascii" for ASCII diagrams
(e.g., the block starting with "You can always go back:" and the other diagram
blocks), "bash" for shell/command examples, "yaml" for schema examples, and
"json" for configuration/JSON examples; apply these changes to all affected
blocks called out in the comment (the ranges listed and any similar blocks) so
every fenced block has a language identifier.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/experimental-workflow.md
🧰 Additional context used
🧠 Learnings (8)
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
docs/experimental-workflow.md
🪛 markdownlint-cli2 (0.18.1)
docs/experimental-workflow.md
19-19: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
64-64: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
69-69: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
75-75: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
81-81: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
103-103: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
149-149: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
170-170: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
209-209: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
237-237: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
248-248: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
269-269: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
307-307: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
326-326: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
348-348: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
docs/experimental-workflow.md (3)
1-108: Strong foundation for OPSX documentation.The introduction, philosophy, and problem statement are clear and compelling. The "problem with linear workflows" framing (lines 11–12) effectively motivates the OPSX approach, and the ASCII backtracking diagram (lines 19–30) illustrates the key difference concisely. The comparison table (lines 86–95) is a good reference point for readers familiar with the standard workflow.
97-387: Architecture Deep Dive is comprehensive and well-structured.The progression from philosophy (phases vs. actions) through component architecture, DAG model, information flow, and iteration patterns provides a thorough mental model for understanding OPSX. The custom schema example (lines 344–376) is particularly valuable for users wanting to tailor the workflow. ASCII diagrams and side-by-side comparisons effectively illustrate the differences between standard and OPSX approaches.
55-84: Usage section and Tips are practical and actionable.The examples for each command are clear, and the tips reinforce the fluid iteration model described in the architecture section. The distinction between
/opsx:ff(for known workflows) and/opsx:continue(for exploration) is well-articulated.Also applies to: 398-403
| ``` | ||
| proposal → specs → design → tasks → implementation → archive | ||
| ``` | ||
| You can always go back: | ||
| Each artifact has dependencies. Can't write tasks until you have specs. Can't implement until you have tasks. The system tracks what's ready and what's blocked. | ||
| ┌────────────────────────────────────┐ | ||
| │ │ | ||
| ▼ │ | ||
| proposal ──→ specs ──→ design ──→ tasks ──→ implement | ||
| ▲ ▲ ▲ │ | ||
| │ │ │ │ | ||
| └───────────┴──────────┴───────────────┘ | ||
| update as you learn | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks (MD040).
All fenced code blocks should specify a language for consistent syntax highlighting and compliance with markdown linting standards. The blocks in this file contain ASCII diagrams, shell commands, YAML schemas, and pseudo-code — each should have an appropriate language identifier.
🔧 Proposed fixes by block type
For ASCII diagrams and flow examples (lines 19–30, 103–143, 149–166, 170–203, 209–233, 237–242, 307–322, 326–342):
Use text or ascii for non-executable diagrams:
-```
+```text
You can always go back:
...
-```
+```For shell/bash examples (lines 64–72, 75–84, 348–376):
Use bash for command examples:
-```
+```bash
/opsx:continue
...
-```
+```For YAML schemas (lines 348–376):
Use yaml for schema examples:
-```
+```yaml
name: research-first
artifacts:
...
-```
+```For configuration/JSON blocks (lines 248–265, 269–301):
Use json or text as appropriate:
-```
+```json
{
"artifacts": [
...
-```
+```Also applies to: 64-72, 75-84, 103-143, 149-166, 170-203, 209-233, 237-242, 248-265, 269-301, 307-322, 326-342, 348-376
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
19-19: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @docs/experimental-workflow.md around lines 19 - 30, The fenced code blocks
in docs/experimental-workflow.md are missing language identifiers (MD040);
update each triple-backtick block to include an appropriate language tag: use
"text" or "ascii" for ASCII diagrams (e.g., the block starting with "You can
always go back:" and the other diagram blocks), "bash" for shell/command
examples, "yaml" for schema examples, and "json" for configuration/JSON
examples; apply these changes to all affected blocks called out in the comment
(the ranges listed and any similar blocks) so every fenced block has a language
identifier.
Add "Why We Built This" section explaining the meta-level motivation: - Instructions were hardcoded, hard to improve - Needed granular, testable artifacts - Wanted to experiment with different workflows without code changes - OPSX makes the instruction system itself hackable Update README banner and experimental features section to highlight schema-driven, hackable nature alongside fluid iteration benefits.
OPSX isn't just for OpenSpec devs to experiment - it's for everyone: - Teams can create workflows that match how they work - Power users can tweak prompts to get better AI outputs - Contributors can experiment without releases Updated framing from "we needed" to "now anyone can".
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @docs/experimental-workflow.md:
- Around line 27-37: The document has many fenced code blocks missing language
specifiers (markdownlint MD040); update each fenced block to include the
appropriate language: mark ASCII/diagram blocks (e.g., the diagram block shown
at the top and other similar blocks at ranges like 56-67, 140-180, 186-203,
etc.) with ```text, mark the YAML schema example (the schema section around
lines ~385-413 / the YAML snippet labeled name: research-first) with ```yaml,
and mark shell/command examples (e.g., the bash examples around lines 101-109,
106-109, 112-115, 118-121 and other command blocks in ranges 246-270, 274-279,
285-302, 306-338, 344-359, 363-379) with ```bash; ensure every triple-backtick
fence in the file has the correct language token.
In @README.md:
- Around line 391-397: The fenced ASCII diagram block is missing a language
specifier (violates MD040); update the triple-backtick fence that wraps the
diagram (the block starting with the ASCII workflow "proposal ──→ specs ──→
design...") to include a language identifier such as text or plaintext (e.g.,
change ``` to ```text) so the diagram is treated as plain text by markdown
linters and renderers.
🧹 Nitpick comments (2)
docs/experimental-workflow.md (2)
134-413: Architecture Deep Dive is comprehensive and well-structured.The section builds progressively from high-level philosophy (Phases vs Actions) through concrete component architecture, dependency graph modeling, information flow, and iteration patterns. Each subsection uses clear diagrams and examples. The custom schemas subsection demonstrates extensibility effectively, and the summary table provides a concise reference.
Minor note: The depth here is excellent for power users and contributors but may overwhelm newcomers. Consider the intended audience—if this doc is entry-point documentation, you might want a shorter "Quick Start" variant or a callout directing users to "continue to Architecture Deep Dive for advanced customization."
426-445: Schemas and Tips sections are functional but could be expanded.The Schemas section is brief (3 lines) and simply lists available schemas without examples. Consider adding a one-line description of what each schema optimizes for. Similarly, the Tips section is sparse; the first tip references
/opsx:ffand/opsx:continuewithout providing clear guidance on when to choose each.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
README.mddocs/experimental-workflow.md
🧰 Additional context used
🧠 Learnings (10)
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
docs/experimental-workflow.mdREADME.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
docs/experimental-workflow.mdREADME.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
docs/experimental-workflow.mdREADME.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
docs/experimental-workflow.mdREADME.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
docs/experimental-workflow.mdREADME.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
README.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
README.md
🪛 markdownlint-cli2 (0.18.1)
docs/experimental-workflow.md
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
56-56: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
101-101: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
112-112: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
118-118: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
140-140: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
186-186: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
207-207: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
246-246: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
274-274: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
285-285: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
306-306: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
344-344: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
363-363: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
385-385: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
README.md
391-391: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (4)
README.md (1)
29-31: Banner and Experimental Features section are well-integrated.The new banner clearly signals the OPSX experimental workflow, and the collapsible section provides concise context with accurate command descriptions and a direct link to full documentation. Navigation between README and
docs/experimental-workflow.mdis clear.Also applies to: 399-409
docs/experimental-workflow.md (3)
11-44: "Why This Exists" section effectively reframes OPSX as an accessibility enabler.The section clearly articulates the pain points with the standard workflow (hardcoded, all-or-nothing, black-box) and positions OPSX as a solution that empowers teams, power users, and contributors. This aligns well with the PR objective to reframe hackability as a user-facing benefit rather than internal capability.
46-67: "The User Experience" section provides clear mental model shift.The narrative effectively contrasts linear phases with fluid actions, and the diagram clearly shows that any artifact can be updated anytime. This reinforces the core OPSX philosophy and helps users understand when/why they'd use it over the standard workflow.
123-131: "What's Different?" comparison table is concise and actionable.The side-by-side comparison of Standard vs OPSX across structure, workflow, iteration, and customization dimensions helps users quickly understand the tradeoffs. The closing insight is crisp.
| ``` | ||
| proposal → specs → design → tasks → implementation → archive | ||
| Standard workflow: OPSX: | ||
| ┌────────────────────────┐ ┌────────────────────────┐ | ||
| │ Hardcoded in package │ │ schema.yaml │◄── You edit this | ||
| │ (can't change) │ │ templates/*.md │◄── Or this | ||
| │ ↓ │ │ ↓ │ | ||
| │ Wait for new release │ │ Instant effect │ | ||
| │ ↓ │ │ ↓ │ | ||
| │ Hope it's better │ │ Test it yourself │ | ||
| └────────────────────────┘ └────────────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Add language specifiers to all fenced code blocks (markdownlint MD040).
Multiple fenced code blocks throughout the document lack language specifiers. Specify the appropriate language for each:
- ASCII diagrams (most blocks): use ````text`
- YAML schema example (around line 393-408): use ````yaml`
- Bash command examples (lines 101-109, 106-109, 112-115, 118-121): use ````bash`
📝 Example fixes
For ASCII diagrams (e.g., lines 27-37):
- ```
+ ```text
Standard workflow: OPSX:
...
For YAML schema (lines 385-413):
```diff
~/.local/share/openspec/schemas/research-first/
├── schema.yaml
└── templates/
...
- schema.yaml:
- ┌─────────────────────────────────────────────────────────────────┐
- │ name: research-first │
+ ```yaml
+ name: research-first
For bash examples (e.g., lines 101-109):
- ### Create artifacts
- ```
+ ### Create artifacts
+ ```bash
/opsx:continue</details>
Also applies to: 56-67, 101-109, 106-109, 112-115, 118-121, 140-180, 186-203, 207-240, 246-270, 274-279, 285-302, 306-338, 344-359, 363-379, 385-413
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @docs/experimental-workflow.md around lines 27 - 37, The document has many
fenced code blocks missing language specifiers (markdownlint MD040); update each
fenced block to include the appropriate language: mark ASCII/diagram blocks
(e.g., the diagram block shown at the top and other similar blocks at ranges
like 56-67, 140-180, 186-203, etc.) with text, mark the YAML schema example (the schema section around lines ~385-413 / the YAML snippet labeled name: research-first) with yaml, and mark shell/command examples (e.g., the bash
examples around lines 101-109, 106-109, 112-115, 118-121 and other command
blocks in ranges 246-270, 274-279, 285-302, 306-338, 344-359, 363-379) with
token.
| ``` | ||
| You can always go back: | ||
| proposal ──→ specs ──→ design ──→ tasks ──→ implement | ||
| ▲ ▲ ▲ │ | ||
| └───────────┴──────────┴────────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to ASCII diagram fenced code block.
The fenced code block containing the workflow diagram is missing a language identifier. Per markdownlint (MD040), specify the language or use text/plaintext for ASCII diagrams.
📝 Proposed fix
You can always go back:
- ```
+ ```text
proposal ──→ specs ──→ design ──→ tasks ──→ implement
▲ ▲ ▲ │
└───────────┴──────────┴────────────────────┘</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>
391-391: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @README.md around lines 391 - 397, The fenced ASCII diagram block is missing
a language specifier (violates MD040); update the triple-backtick fence that
wraps the diagram (the block starting with the ASCII workflow "proposal ──→
specs ──→ design...") to include a language identifier such as text or plaintext
(e.g., change totext) so the diagram is treated as plain text by
markdown linters and renderers.
</details>
<!-- fingerprinting:phantom:triton:mongoose -->
<!-- This is an auto-generated comment by CodeRabbit -->
Addresses a common question: when does "update as you learn" become "this is different work"? Adds heuristics based on intent, scope overlap, and completability to help users make the judgment call.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @docs/experimental-workflow.md:
- Line 138: Replace the bolded subsection lines that use emphasis syntax (e.g.,
"**Same intent, refined execution**", "**Intent fundamentally changed**" and the
other bolded strings at the mentioned locations) with proper markdown headings
(use a consistent level like "### Same intent, refined execution", "### Intent
fundamentally changed", etc.), ensuring you remove the surrounding ** markers
and prefix each with the chosen heading marker so the sections comply with MD036
and improve semantic structure.
- Line 27: Update the fenced code blocks to include explicit language
identifiers: mark ASCII diagrams with ```text, shell/CLI examples with ```bash,
and the YAML schema example with ```yaml (or remove fencing for pure ASCII art
and use indented blocks); apply these changes to each fenced block flagged by
MD040 so linters recognize the correct language instead of leaving backticks
unannotated.
🧹 Nitpick comments (2)
docs/experimental-workflow.md (2)
521-526: Consider expanding Tips and adding Troubleshooting section.The Tips section is brief relative to the comprehensive documentation. Consider adding:
- Common gotchas and how to recover (e.g., "accidentally created the wrong artifact")
- How to debug if dependencies aren't detected
- When to use
/opsx:ffvs. repeated/opsx:continue- How to inspect current state if unsure
This would improve practical usability without requiring a separate troubleshooting page.
87-87: Consider clarifying "fast-forward" terminology for non-git-familiar readers.The
/opsx:ffcommand uses "fast-forward" which may evoke git usage (replaying commits). While the description "creates all planning artifacts at once" is clear, a brief parenthetical clarification (e.g., "fast-forward — not like git, but like skipping steps when you know where you're going") might prevent confusion.Also applies to: 109-109
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/experimental-workflow.md
🧰 Additional context used
🧠 Learnings (11)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/specs/**/spec.md : Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally non-normative
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `file.ts:42` format for code location references and `specs/auth/spec.md` format for spec references
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
docs/experimental-workflow.md
🪛 markdownlint-cli2 (0.18.1)
docs/experimental-workflow.md
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
56-56: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
101-101: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
112-112: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
118-118: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
138-138: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
143-143: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
147-147: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
154-154: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
158-158: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
163-163: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
170-170: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
226-226: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
272-272: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
293-293: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
332-332: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
360-360: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
371-371: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
392-392: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
430-430: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
449-449: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
471-471: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
docs/experimental-workflow.md (1)
1-9: Excellent reframing and motivation.The new "Why This Exists" and "The User Experience" sections effectively explain OPSX's philosophy and address the pain points of linear workflows. The progression from "what" → "why" → "how to use" → "when to decide" → "architecture" is pedagogically sound and provides multiple entry points for different reader needs.
| 3. **Customize workflows** — define your own artifacts and dependencies | ||
| 4. **Iterate quickly** — change a template, test immediately, no rebuild | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Specify language identifiers for fenced code blocks (or remove fencing for ASCII diagrams).
Lines 27, 56, 101, 106, 112, 118, 170, 226, 272, 293, 332, 360, 371, 392, 430, 449, and 471 trigger MD040. ASCII diagrams and shell commands need language specifiers. For pure ASCII art, consider removing fence backticks and using indentation instead, or specify text as the language.
Suggested fixes for code blocks
For shell commands (e.g., lines 101, 106, 112, 118), add bash:
-```
+```bash
/opsx:continue
-```
+```For ASCII diagrams (e.g., lines 27, 56, 170, 226, 272, etc.), use text:
-```
+```text
Standard workflow: OPSX:
...
-```
+```For YAML (e.g., line 471 in schema example), add yaml:
-```
+```yaml
name: research-first
...
-```
+```Also applies to: 56-56, 101-101, 106-106, 112-112, 118-118, 170-170, 226-226, 272-272, 293-293, 332-332, 360-360, 371-371, 392-392, 430-430, 449-449, 471-471
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @docs/experimental-workflow.md at line 27, Update the fenced code blocks to
include explicit language identifiers: mark ASCII diagrams with ```text,
shell/CLI examples with ```bash, and the YAML schema example with ```yaml (or
remove fencing for pure ASCII art and use indented blocks); apply these changes
to each fenced block flagged by MD040 so linters recognize the correct language
instead of leaving backticks unannotated.
|
|
||
| ### Update the Existing Change When: | ||
|
|
||
| **Same intent, refined execution** |
There was a problem hiding this comment.
Convert emphasis-styled subheadings to proper markdown headings.
Lines 138, 143, 147, 154, 158, and 163 use bold emphasis for subsections (e.g., **Same intent, refined execution**, **Intent fundamentally changed**) instead of proper markdown headings (### level). This triggers MD036 and reduces document semantic clarity.
Suggested fixes for subheadings
### Update the Existing Change When:
- **Same intent, refined execution**
+ ### Same intent, refined execution
- You discover edge cases you didn't consider
...
- **Scope narrows**
+ ### Scope narrows
- You realize full scope is too big, want to ship MVP first
...
- **Learning-driven corrections**
+ ### Learning-driven corrections
- Codebase isn't structured how you thought
...
### Start a New Change When:
- **Intent fundamentally changed**
+ ### Intent fundamentally changed
- The problem itself is different now
...
- **Scope exploded**
+ ### Scope exploded
- Change grew so much it's essentially different work
...
- **Original is completable**
+ ### Original is completable
- The original change can be marked "done"Also applies to: 143-143, 147-147, 154-154, 158-158, 163-163
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
138-138: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In @docs/experimental-workflow.md at line 138, Replace the bolded subsection
lines that use emphasis syntax (e.g., "**Same intent, refined execution**",
"**Intent fundamentally changed**" and the other bolded strings at the mentioned
locations) with proper markdown headings (use a consistent level like "### Same
intent, refined execution", "### Intent fundamentally changed", etc.), ensuring
you remove the surrounding ** markers and prefix each with the chosen heading
marker so the sections comply with MD036 and improve semantic structure.
Summary
Test plan
docs/experimental-workflow.mdwork🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.