@fro.bot/systematic 1.22.8 → 1.23.1

package/skills/ce-brainstorm/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: ce:brainstorm
+description: Explore requirements and approaches through collaborative dialogue before writing a right-sized requirements document and planning implementation. Use for feature ideas, problem framing, when the user says 'let's brainstorm', or when they want to think through options before deciding what to build. Also use when a user describes a vague or ambitious feature request, asks 'what should we build', 'help me think through X', presents a problem with multiple valid solutions, or seems unsure about scope or direction — even if they don't explicitly ask to brainstorm.
+argument-hint: '[feature idea or problem to explore]'
+---
+
+# Brainstorm a Feature or Improvement
+
+**Note: The current year is 2026.** Use this when dating requirements documents.
+
+Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/systematic:ce-plan`, which answers **HOW** to build it.
+
+The durable output of this workflow is a **requirements document**. In other workflows this might be called a lightweight PRD or feature brief. In compound engineering, keep the workflow name `brainstorm`, but make the written artifact strong enough that planning does not need to invent product behavior, scope boundaries, or success criteria.
+
+This skill does not implement code. It explores, clarifies, and documents decisions for later planning or execution.
+
+## Core Principles
+
+1. **Assess scope first** - Match the amount of ceremony to the size and ambiguity of the work.
+2. **Be a thinking partner** - Suggest alternatives, challenge assumptions, and explore what-ifs instead of only extracting requirements.
+3. **Resolve product decisions here** - User-facing behavior, scope boundaries, and success criteria belong in this workflow. Detailed implementation belongs in planning.
+4. **Keep implementation out of the requirements doc by default** - Do not include libraries, schemas, endpoints, file layouts, or code-level design unless the brainstorm itself is inherently about a technical or architectural change.
+5. **Right-size the artifact** - Simple work gets a compact requirements document or brief alignment. Larger work gets a fuller document. Do not add ceremony that does not help planning.
+6. **Apply YAGNI to carrying cost, not coding effort** - Prefer the simplest approach that delivers meaningful value. Avoid speculative complexity and hypothetical future-proofing, but low-cost polish or delight is worth including when its ongoing cost is small and easy to maintain.
+
+## Interaction Rules
+
+1. **Ask one question at a time** - Do not batch several unrelated questions into one message.
+2. **Prefer single-select multiple choice** - Use single-select when choosing one direction, one priority, or one next step.
+3. **Use multi-select rarely and intentionally** - Use it only for compatible sets such as goals, constraints, non-goals, or success criteria that can all coexist. If prioritization matters, follow up by asking which selected item is primary.
+4. **Use the platform's question tool when available** - When asking the user a question, prefer the platform's blocking question tool if one exists (`AskUserQuestion` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+
+## Output Guidance
+
+- **Keep outputs concise** - Prefer short sections, brief bullets, and only enough detail to support the next decision.
+
+## Feature Description
+
+<feature_description> #$ARGUMENTS </feature_description>
+
+**If the feature description above is empty, ask the user:** "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
+
+Do not proceed until you have a feature description from the user.
+
+## Execution Flow
+
+### Phase 0: Resume, Assess, and Route
+
+#### 0.1 Resume Existing Work When Appropriate
+
+If the user references an existing brainstorm topic or document, or there is an obvious recent matching `*-requirements.md` file in `docs/brainstorms/`:
+- Read the document
+- Confirm with the user before resuming: "Found an existing requirements doc for [topic]. Should I continue from this, or start fresh?"
+- If resuming, summarize the current state briefly, continue from its existing decisions and outstanding questions, and update the existing document instead of creating a duplicate
+
+#### 0.2 Assess Whether Brainstorming Is Needed
+
+**Clear requirements indicators:**
+- Specific acceptance criteria provided
+- Referenced existing patterns to follow
+- Described exact expected behavior
+- Constrained, well-defined scope
+
+**If requirements are already clear:**
+Keep the interaction brief. Confirm understanding and present concise next-step options rather than forcing a long brainstorm. Only write a short requirements document when a durable handoff to planning or later review would be valuable. Skip Phase 1.1 and 1.2 entirely — go straight to Phase 1.3 or Phase 3.
+
+#### 0.3 Assess Scope
+
+Use the feature description plus a light repo scan to classify the work:
+- **Lightweight** - small, well-bounded, low ambiguity
+- **Standard** - normal feature or bounded refactor with some decisions to make
+- **Deep** - cross-cutting, strategic, or highly ambiguous
+
+If the scope is unclear, ask one targeted question to disambiguate and then proceed.
+
+### Phase 1: Understand the Idea
+
+#### 1.1 Existing Context Scan
+
+Scan the repo before substantive brainstorming. Match depth to scope:
+
+**Lightweight** — Search for the topic, check if something similar already exists, and move on.
+
+**Standard and Deep** — Two passes:
+
+*Constraint Check* — Check project instruction files (`AGENTS.md`, `CLAUDE.md`) for workflow, product, or scope constraints that affect the brainstorm. If these add nothing, move on.
+
+*Topic Scan* — Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc). Skim adjacent examples covering similar behavior.
+
+If nothing obvious appears after a short scan, say so and continue. Do not drift into technical planning — avoid inspecting tests, migrations, deployment, or low-level architecture unless the brainstorm is itself about a technical decision.
+
+#### 1.2 Product Pressure Test
+
+Before generating approaches, challenge the request to catch misframing. Match depth to scope:
+
+**Lightweight:**
+- Is this solving the real user problem?
+- Are we duplicating something that already covers this?
+- Is there a clearly better framing with near-zero extra cost?
+
+**Standard:**
+- Is this the right problem, or a proxy for a more important one?
+- What user or business outcome actually matters here?
+- What happens if we do nothing?
+- Is there a nearby framing that creates more user value without more carrying cost? If so, what complexity does it add?
+- Given the current project state, user goal, and constraints, what is the single highest-leverage move right now: the request as framed, a reframing, one adjacent addition, a simplification, or doing nothing?
+- Favor moves that compound value, reduce future carrying cost, or make the product meaningfully more useful or compelling
+- Use the result to sharpen the conversation, not to bulldoze the user's intent
+
+**Deep** — Standard questions plus:
+- What durable capability should this create in 6-12 months?
+- Does this move the product toward that, or is it only a local patch?
+
+#### 1.3 Collaborative Dialogue
+
+Use the platform's blocking question tool when available (see Interaction Rules). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+
+**Guidelines:**
+- Ask questions **one at a time**
+- Prefer multiple choice when natural options exist
+- Prefer **single-select** when choosing one direction, one priority, or one next step
+- Use **multi-select** only for compatible sets that can all coexist; if prioritization matters, ask which selected item is primary
+- Start broad (problem, users, value) then narrow (constraints, exclusions, edge cases)
+- Clarify the problem frame, validate assumptions, and ask about success criteria
+- Make requirements concrete enough that planning will not need to invent behavior
+- Surface dependencies or prerequisites only when they materially affect scope
+- Resolve product decisions here; leave technical implementation choices for planning
+- Bring ideas, alternatives, and challenges instead of only interviewing
+
+**Exit condition:** Continue until the idea is clear OR the user explicitly wants to proceed.
+
+### Phase 2: Explore Approaches
+
+If multiple plausible directions remain, propose **2-3 concrete approaches** based on research and conversation. Otherwise state the recommended direction directly.
+
+When useful, include one deliberately higher-upside alternative:
+- Identify what adjacent addition or reframing would most increase usefulness, compounding value, or durability without disproportionate carrying cost. Present it as a challenger option alongside the baseline, not as the default. Omit it when the work is already obviously over-scoped or the baseline request is clearly the right move.
+
+For each approach, provide:
+- Brief description (2-3 sentences)
+- Pros and cons
+- Key risks or unknowns
+- When it's best suited
+
+Lead with your recommendation and explain why. Prefer simpler solutions when added complexity creates real carrying cost, but do not reject low-cost, high-value polish just because it is not strictly necessary.
+
+If one approach is clearly best and alternatives are not meaningful, skip the menu and state the recommendation directly.
+
+If relevant, call out whether the choice is:
+- Reuse an existing pattern
+- Extend an existing capability
+- Build something net new
+
+### Phase 3: Capture the Requirements
+
+Write or update a requirements document only when the conversation produced durable decisions worth preserving.
+
+This document should behave like a lightweight PRD without PRD ceremony. Include what planning needs to execute well, and skip sections that add no value for the scope.
+
+The requirements document is for product definition and scope control. Do **not** include implementation details such as libraries, schemas, endpoints, file layouts, or code structure unless the brainstorm is inherently technical and those details are themselves the subject of the decision.
+
+**Required content for non-trivial work:**
+- Problem frame
+- Concrete requirements or intended behavior with stable IDs
+- Scope boundaries
+- Success criteria
+
+**Include when materially useful:**
+- Key decisions and rationale
+- Dependencies or assumptions
+- Outstanding questions
+- Alternatives considered
+- High-level technical direction only when the work is inherently technical and the direction is part of the product/architecture decision
+
+**Document structure:** Use this template and omit clearly inapplicable optional sections:
+
+```markdown
+---
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+---
+
+# <Topic Title>
+
+## Problem Frame
+[Who is affected, what is changing, and why it matters]
+
+## Requirements
+- R1. [Concrete user-facing behavior or requirement]
+- R2. [Concrete user-facing behavior or requirement]
+
+## Success Criteria
+- [How we will know this solved the right problem]
+
+## Scope Boundaries
+- [Deliberate non-goal or exclusion]
+
+## Key Decisions
+- [Decision]: [Rationale]
+
+## Dependencies / Assumptions
+- [Only include if material]
+
+## Outstanding Questions
+
+### Resolve Before Planning
+- [Affects R1][User decision] [Question that must be answered before planning can proceed]
+
+### Deferred to Planning
+- [Affects R2][Technical] [Question that should be answered during planning or codebase exploration]
+- [Affects R2][Needs research] [Question that likely requires research during planning]
+
+## Next Steps
+[If `Resolve Before Planning` is empty: `→ /systematic:ce-plan` for structured implementation planning]
+[If `Resolve Before Planning` is not empty: `→ Resume /systematic:ce-brainstorm` to resolve blocking questions before planning]
+```
+
+For **Standard** and **Deep** brainstorms, a requirements document is usually warranted.
+
+For **Lightweight** brainstorms, keep the document compact. Skip document creation when the user only needs brief alignment and no durable decisions need to be preserved.
+
+For very small requirements docs with only 1-3 simple requirements, plain bullet requirements are acceptable. For **Standard** and **Deep** requirements docs, use stable IDs like `R1`, `R2`, `R3` so planning and later review can refer to them unambiguously.
+
+When the work is simple, combine sections rather than padding them. A short requirements document is better than a bloated one.
+
+Before finalizing, check:
+- What would `ce:plan` still have to invent if this brainstorm ended now?
+- Do any requirements depend on something claimed to be out of scope?
+- Are any unresolved items actually product decisions rather than planning questions?
+- Did implementation details leak in when they shouldn't have?
+- Is there a low-cost change that would make this materially more useful?
+
+If planning would need to invent product behavior, scope boundaries, or success criteria, the brainstorm is not complete yet.
+
+Ensure `docs/brainstorms/` directory exists before writing.
+
+If a document contains outstanding questions:
+- Use `Resolve Before Planning` only for questions that truly block planning
+- If `Resolve Before Planning` is non-empty, keep working those questions during the brainstorm by default
+- If the user explicitly wants to proceed anyway, convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question before proceeding
+- Do not force resolution of technical questions during brainstorming just to remove uncertainty
+- Put technical questions, or questions that require validation or research, under `Deferred to Planning` when they are better answered there
+- Use tags like `[Needs research]` when the planner should likely investigate the question rather than answer it from repo context alone
+- Carry deferred questions forward explicitly rather than treating them as a failure to finish the requirements doc
+
+### Phase 4: Handoff
+
+#### 4.1 Present Next-Step Options
+
+Present next steps using the platform's blocking question tool when available (see Interaction Rules). Otherwise present numbered options in chat and end the turn.
+
+If `Resolve Before Planning` contains any items:
+- Ask the blocking questions now, one at a time, by default
+- If the user explicitly wants to proceed anyway, first convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question
+- If the user chooses to pause instead, present the handoff as paused or blocked rather than complete
+- Do not offer `Proceed to planning` or `Proceed directly to work` while `Resolve Before Planning` remains non-empty
+
+**Question when no blocking questions remain:** "Brainstorm complete. What would you like to do next?"
+
+**Question when blocking questions remain and user wants to pause:** "Brainstorm paused. Planning is blocked until the remaining questions are resolved. What would you like to do next?"
+
+Present only the options that apply:
+- **Proceed to planning (Recommended)** - Run `/systematic:ce-plan` for structured implementation planning
+- **Proceed directly to work** - Only offer this when scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain
+- **Review and refine** - Offer this only when a requirements document exists and can be improved through structured review
+- **Ask more questions** - Continue clarifying scope, preferences, or edge cases
+- **Share to Proof** - Offer this only when a requirements document exists
+- **Done for now** - Return later
+
+If the direct-to-work gate is not satisfied, omit that option entirely.
+
+#### 4.2 Handle the Selected Option
+
+**If user selects "Proceed to planning (Recommended)":**
+
+Immediately run `/systematic:ce-plan` in the current session. Pass the requirements document path when one exists; otherwise pass a concise summary of the finalized brainstorm decisions. Do not print the closing summary first.
+
+**If user selects "Proceed directly to work":**
+
+Immediately run `/systematic:ce-work` in the current session using the finalized brainstorm output as context. If a compact requirements document exists, pass its path. Do not print the closing summary first.
+
+**If user selects "Share to Proof":**
+
+```bash
+CONTENT=$(cat docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md)
+TITLE="Requirements: <topic title>"
+RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
+PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
+```
+
+Display the URL prominently: `View & collaborate in Proof: <PROOF_URL>`
+
+If the curl fails, skip silently. Then return to the Phase 4 options.
+
+**If user selects "Ask more questions":** Return to Phase 1.3 (Collaborative Dialogue) and continue asking the user questions one at a time to further refine the design. Probe deeper into edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4. Do not show the closing summary yet.
+
+**If user selects "Review and refine":**
+
+Load the `document-review` skill and apply it to the requirements document.
+
+When document-review returns "Review complete", return to the normal Phase 4 options and present only the options that still apply. Do not show the closing summary yet.
+
+#### 4.3 Closing Summary
+
+Use the closing summary only when this run of the workflow is ending or handing off, not when returning to the Phase 4 options.
+
+When complete and ready for planning, display:
+
+```text
+Brainstorm complete!
+
+Requirements doc: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if one was created
+
+Key decisions:
+- [Decision 1]
+- [Decision 2]
+
+Recommended next step: `/systematic:ce-plan`
+```
+
+If the user pauses with `Resolve Before Planning` still populated, display:
+
+```text
+Brainstorm paused.
+
+Requirements doc: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if one was created
+
+Planning is blocked by:
+- [Blocking question 1]
+- [Blocking question 2]
+
+Resume with `/systematic:ce-brainstorm` when ready to resolve these before planning.
+```
+

package/{commands/ce/compound.md → skills/ce-compound/SKILL.md}

@@ -1,7 +1,7 @@
 ---
 name: ce:compound
 description: Document a recently solved problem to compound your team's knowledge
-argument-hint: "[optional: brief context about the fix]"
+argument-hint: '[optional: brief context about the fix]'
 ---
 
 # /compound
@@ -17,11 +17,19 @@ Captures problem solutions while context is fresh, creating structured documenta
 ## Usage
 
 ```bash
-/ce:compound                    # Document the most recent fix
-/ce:compound [brief context]    # Provide additional context hint
+/systematic:ce-compound                    # Document the most recent fix
+/systematic:ce-compound [brief context]    # Provide additional context hint
 ```
 
-## Execution Strategy: Two-Phase Orchestration
+## Execution Strategy
+
+**Always run full mode by default.** Proceed directly to Phase 1 unless the user explicitly requests compact-safe mode (e.g., `/systematic:ce-compound --compact` or "use compact mode").
+
+Compact-safe mode exists as a lightweight alternative — see the **Compact-Safe Mode** section below. It's there if the user wants it, not something to push.
+
+---
+
+### Full Mode
 
 <critical_requirement>
 **Only ONE file gets written - the final documentation.**
@@ -51,7 +59,8 @@ Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
    - Searches `docs/solutions/` for related documentation
    - Identifies cross-references and links
    - Finds related GitHub issues
-   - Returns: Links and relationships
+   - Flags any related learning or pattern docs that may now be stale, contradicted, or overly broad
+   - Returns: Links, relationships, and any refresh candidates
 
 #### 4. **Prevention Strategist**
    - Develops prevention strategies
@@ -83,6 +92,53 @@ The orchestrating agent (main conversation) performs these steps:
 
 </sequential_tasks>
 
+### Phase 2.5: Selective Refresh Check
+
+After writing the new learning, decide whether this new solution is evidence that older docs should be refreshed.
+
+`ce:compound-refresh` is **not** a default follow-up. Use it selectively when the new learning suggests an older learning or pattern doc may now be inaccurate.
+
+It makes sense to invoke `ce:compound-refresh` when one or more of these are true:
+
+1. A related learning or pattern doc recommends an approach that the new fix now contradicts
+2. The new fix clearly supersedes an older documented solution
+3. The current work involved a refactor, migration, rename, or dependency upgrade that likely invalidated references in older docs
+4. A pattern doc now looks overly broad, outdated, or no longer supported by the refreshed reality
+5. The Related Docs Finder surfaced high-confidence refresh candidates in the same problem space
+
+It does **not** make sense to invoke `ce:compound-refresh` when:
+
+1. No related docs were found
+2. Related docs still appear consistent with the new learning
+3. The overlap is superficial and does not change prior guidance
+4. Refresh would require a broad historical review with weak evidence
+
+Use these rules:
+
+- If there is **one obvious stale candidate**, invoke `ce:compound-refresh` with a narrow scope hint after the new learning is written
+- If there are **multiple candidates in the same area**, ask the user whether to run a targeted refresh for that module, category, or pattern set
+- If context is already tight or you are in compact-safe mode, do not expand into a broad refresh automatically; instead recommend `ce:compound-refresh` as the next step with a scope hint
+
+When invoking or recommending `ce:compound-refresh`, be explicit about the argument to pass. Prefer the narrowest useful scope:
+
+- **Specific file** when one learning or pattern doc is the likely stale artifact
+- **Module or component name** when several related docs may need review
+- **Category name** when the drift is concentrated in one solutions area
+- **Pattern filename or pattern topic** when the stale guidance lives in `docs/solutions/patterns/`
+
+Examples:
+
+- `/systematic:ce-compound-refresh plugin-versioning-requirements`
+- `/systematic:ce-compound-refresh payments`
+- `/systematic:ce-compound-refresh performance-issues`
+- `/systematic:ce-compound-refresh critical-patterns`
+
+A single scope hint may still expand to multiple related docs when the change is cross-cutting within one domain, category, or pattern area.
+
+Do not invoke `ce:compound-refresh` without an argument unless the user explicitly wants a broad sweep.
+
+Always capture the new learning first. Refresh is a targeted maintenance follow-up, not a prerequisite for documentation.
+
 ### Phase 3: Optional Enhancement
 
 **WAIT for Phase 2 to complete before proceeding.**
@@ -99,6 +155,46 @@ Based on problem type, optionally invoke specialized agents to review the docume
 
 </parallel_tasks>
 
+---
+
+### Compact-Safe Mode
+
+<critical_requirement>
+**Single-pass alternative for context-constrained sessions.**
+
+When context budget is tight, this mode skips parallel subagents entirely. The orchestrator performs all work in a single pass, producing a minimal but complete solution document.
+</critical_requirement>
+
+The orchestrator (main conversation) performs ALL of the following in one sequential pass:
+
+1. **Extract from conversation**: Identify the problem, root cause, and solution from conversation history
+2. **Classify**: Determine category and filename (same categories as full mode)
+3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` with:
+   - YAML frontmatter (title, category, date, tags)
+   - Problem description (1-2 sentences)
+   - Root cause (1-2 sentences)
+   - Solution with key code snippets
+   - One prevention tip
+4. **Skip specialized agent reviews** (Phase 3) to conserve context
+
+**Compact-safe output:**
+```
+✓ Documentation complete (compact-safe mode)
+
+File created:
+- docs/solutions/[category]/[filename].md
+
+Note: This was created in compact-safe mode. For richer documentation
+(cross-references, detailed prevention strategies, specialized reviews),
+re-run /compound in a fresh session.
+```
+
+**No subagents are launched. No parallel tasks. One file written.**
+
+In compact-safe mode, only suggest `ce:compound-refresh` if there is an obvious narrow refresh target. Do not broaden into a large refresh sweep from a compact-safe session.
+
+---
+
 ## What It Captures
 
 - **Problem symptom**: Exact error messages, observable behavior
@@ -203,7 +299,7 @@ Build → Test → Find Issue → Research → Improve → Document → Validate
 
 <auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
 
-<manual_override> Use /ce:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
+<manual_override> Use /systematic:ce-compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
 
 ## Routes To
 
@@ -231,10 +327,11 @@ Based on problem type, these agents can enhance documentation:
 
 ### When to Invoke
 - **Auto-triggered** (optional): Agents can run post-documentation for enhancement
-- **Manual trigger**: User can invoke agents after /ce:compound completes for deeper review
-- **Customize agents**: Edit `systematic.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
+- **Manual trigger**: User can invoke agents after /systematic:ce-compound completes for deeper review
+- **Customize agents**: Edit `compound-engineering.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
 
 ## Related Commands
 
 - `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
-- `/ce:plan` - Planning workflow (references documented solutions)
+- `/systematic:ce-plan` - Planning workflow (references documented solutions)
+