create-yss-spec 1.1.4 → 2.0.0

package/template/.trae/skills/diagnosing-bugs/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Diagnosing Bugs"
+  short_description: "Diagnose hard bugs and regressions"

package/template/.trae/skills/domain-modeling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Domain Modeling"
+  short_description: "Build and sharpen a domain model"

package/template/.trae/skills/excalidraw-diagram-generator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: excalidraw-diagram-generator
-description: 'Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw.'
+description: 'Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "draw business/functional/system/data architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, business flows, system architecture, ER, class, sequence, lineage, and data flow diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw.'
 ---
 
 # Excalidraw Diagram Generator
@@ -31,6 +31,27 @@ Use this skill when users request:
 - 🔄 **Sequence Diagrams**: Object interactions over time, message flows
 - 🗃️ **ER Diagrams**: Database entity relationships, data models
 
+## YSS Lifecycle Integration
+
+In YSS projects, this skill is a visualization and review aid. It can clarify lifecycle artifacts, but it must not replace Discovery, Spec, OpenAPI, ADR, Spec Delta design, or tests.
+
+Use it after the relevant source artifact exists:
+
+| Lifecycle artifact | Typical timing | Useful diagrams | Recommended output |
+|--------------------|----------------|-----------------|--------------------|
+| Business architecture | Opportunity exploration / Discovery | user journey, value stream, swimlane, capability map, ecosystem map | `docs/discovery/diagrams/` or `docs/architecture/diagrams/` |
+| Functional architecture | Spec baseline / product design / Spec calibration | feature map, module map, dependency graph, page map | `docs/design/diagrams/` or `docs/architecture/diagrams/` |
+| System architecture | Engineering baseline / Architecture / Spec Delta design | C4/container view, deployment, sequence, DDD boundary, DFD | `docs/architecture/diagrams/` |
+| Data architecture | Detailed design before persistence / repository work | ER, class, meta-model, lineage graph, query/data-flow diagram | `docs/architecture/diagrams/` |
+
+Guardrails:
+
+- Do not invent product requirements or architecture decisions only from the diagram prompt.
+- Reference the source artifact in the Markdown document that links the `.excalidraw` file.
+- If a diagram exposes a missing field, unclear state, dependency, or boundary problem, write that finding back to the source Spec, OpenAPI Draft, architecture document, ADR, Spec Delta design, or issue.
+- Do not require diagrams for small copy, style, configuration, or single-point bug fixes.
+- For data modeling, metadata management, model versioning, or lineage-analysis products, prefer ER, class/meta-model, DFD, and lineage diagrams before persistence implementation.
+
 ## Prerequisites
 
 - Clear description of what should be visualized
@@ -178,7 +199,7 @@ Structure the complete Excalidraw file:
 ### Layout Tips
 
 1. **Start positions**: Center important elements, use consistent spacing
-2. **Spacing**: 
+2. **Spacing**:
    - Horizontal gap: 200-300px between elements
    - Vertical gap: 100-150px between rows
 3. **Colors**: Use consistent color scheme
@@ -315,18 +336,18 @@ For specialized diagrams (e.g., AWS/GCP/Azure architecture diagrams), you can us
 
    ```
    To use [AWS/GCP/Azure/etc.] architecture icons, please follow these steps:
-   
+
    1. Visit https://libraries.excalidraw.com/
    2. Search for "[AWS Architecture Icons/etc.]" and download the .excalidrawlib file
    3. Create directory: skills/excalidraw-diagram-generator/libraries/[icon-set-name]/
    4. Place the downloaded file in that directory
    5. Run the splitter script:
       python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/[icon-set-name]/
-   
+
    This will split the library into individual icon files for efficient use.
    After setup is complete, I can create your diagram using the actual AWS/cloud icons.
-   
-   Alternatively, I can create the diagram now using simple shapes (rectangles, ellipses) 
+
+   Alternatively, I can create the diagram now using simple shapes (rectangles, ellipses)
    which you can later replace with icons manually in Excalidraw.
    ```
 
@@ -389,15 +410,15 @@ The repository includes Python scripts that handle icon integration automaticall
      <diagram-path> <icon-name> <x> <y> [--label "Text"] [--library-path PATH]
    ```
    - Edit via `.excalidraw.edit` is enabled by default to avoid overwrite issues; pass `--no-use-edit-suffix` to disable.
-   
+
    **Examples**:
    ```bash
    # Add EC2 icon at position (400, 300) with label
    python scripts/add-icon-to-diagram.py diagram.excalidraw EC2 400 300 --label "Web Server"
-   
+
    # Add VPC icon at position (200, 150)
    python scripts/add-icon-to-diagram.py diagram.excalidraw VPC 200 150
-   
+
    # Add icon from different library
    python scripts/add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \
      --library-path libraries/gcp-icons --label "API Server"
@@ -409,15 +430,15 @@ The repository includes Python scripts that handle icon integration automaticall
      <diagram-path> <from-x> <from-y> <to-x> <to-y> [--label "Text"] [--style solid|dashed|dotted] [--color HEX]
    ```
    - Edit via `.excalidraw.edit` is enabled by default to avoid overwrite issues; pass `--no-use-edit-suffix` to disable.
-   
+
    **Examples**:
    ```bash
    # Simple arrow from (300, 250) to (500, 300)
    python scripts/add-arrow.py diagram.excalidraw 300 250 500 300
-   
+
    # Arrow with label
    python scripts/add-arrow.py diagram.excalidraw 300 250 500 300 --label "HTTPS"
-   
+
    # Dashed arrow with custom color
    python scripts/add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"
    ```
@@ -426,14 +447,14 @@ The repository includes Python scripts that handle icon integration automaticall
    ```bash
    # Step 1: Create base diagram with title and structure
    # (Create .excalidraw file with initial elements)
-   
+
    # Step 2: Add icons with labels
    python scripts/add-icon-to-diagram.py my-diagram.excalidraw "Internet-gateway" 200 150 --label "Internet Gateway"
    python scripts/add-icon-to-diagram.py my-diagram.excalidraw VPC 250 250
    python scripts/add-icon-to-diagram.py my-diagram.excalidraw ELB 350 300 --label "Load Balancer"
    python scripts/add-icon-to-diagram.py my-diagram.excalidraw EC2 450 350 --label "EC2 Instance"
    python scripts/add-icon-to-diagram.py my-diagram.excalidraw RDS 550 400 --label "Database"
-   
+
    # Step 3: Add connecting arrows
    python scripts/add-arrow.py my-diagram.excalidraw 250 200 300 250  # Internet → VPC
    python scripts/add-arrow.py my-diagram.excalidraw 300 300 400 300  # VPC → ELB
@@ -453,7 +474,7 @@ The repository includes Python scripts that handle icon integration automaticall
 
 Only use this if Python scripts are unavailable:
 
-1. **Check for libraries**: 
+1. **Check for libraries**:
    ```
    List directory: skills/excalidraw-diagram-generator/libraries/
    Look for subdirectories containing reference.md files
@@ -549,7 +570,7 @@ python scripts/add-arrow.py my-aws-diagram.excalidraw 565 330 650 350 --label "S
    - `icons/Internet-gateway.json` (298 lines)
    - `icons/VPC.json` (550 lines)
    - `icons/ELB.json` (363 lines)
-   - `icons/EC2.json` (231 lines) 
+   - `icons/EC2.json` (231 lines)
    - `icons/RDS.json` (similar size)
    **Total: ~2000+ lines of JSON to process**
 4. Extract elements from each JSON

package/template/.trae/skills/excalidraw-diagram-generator/scripts/add-arrow.py

@@ -77,7 +77,7 @@ def create_arrow(
 ) -> list:
     """
     Create an arrow element.
-    
+
     Args:
         from_x: Starting X coordinate
         from_y: Starting Y coordinate
@@ -86,12 +86,12 @@ def create_arrow(
         style: Line style (solid, dashed, dotted)
         color: Arrow color
         label: Optional text label on the arrow
-    
+
     Returns:
         List of elements (arrow and optional label)
     """
     elements = []
-    
+
     # Arrow element
     arrow = {
         "id": generate_unique_id(),
@@ -133,12 +133,12 @@ def create_arrow(
         "lastCommittedPoint": None
     }
     elements.append(arrow)
-    
+
     # Optional label
     if label:
         mid_x = (from_x + to_x) / 2 - (len(label) * 5)
         mid_y = (from_y + to_y) / 2 - 10
-        
+
         label_element = {
             "id": generate_unique_id(),
             "type": "text",
@@ -177,7 +177,7 @@ def create_arrow(
             "lineHeight": 1.25
         }
         elements.append(label_element)
-    
+
     return elements
 
 
@@ -193,7 +193,7 @@ def add_arrow_to_diagram(
 ) -> None:
     """
     Add an arrow to an Excalidraw diagram.
-    
+
     Args:
         diagram_path: Path to the Excalidraw diagram file
         from_x: Starting X coordinate
@@ -206,28 +206,28 @@ def add_arrow_to_diagram(
     """
     print(f"Creating arrow from ({from_x}, {from_y}) to ({to_x}, {to_y})")
     arrow_elements = create_arrow(from_x, from_y, to_x, to_y, style, color, label)
-    
+
     if label:
         print(f"  With label: '{label}'")
-    
+
     # Load diagram
     print(f"Loading diagram: {diagram_path}")
     with open(diagram_path, 'r', encoding='utf-8') as f:
         diagram = json.load(f)
-    
+
     # Add arrow elements
     if 'elements' not in diagram:
         diagram['elements'] = []
-    
+
     original_count = len(diagram['elements'])
     diagram['elements'].extend(arrow_elements)
     print(f"  Added {len(arrow_elements)} elements (total: {original_count} -> {len(diagram['elements'])})")
-    
+
     # Save diagram
     print(f"Saving diagram")
     with open(diagram_path, 'w', encoding='utf-8') as f:
         json.dump(diagram, f, indent=2, ensure_ascii=False)
-    
+
     print(f"✓ Successfully added arrow to diagram")
 
 
@@ -247,20 +247,20 @@ def main():
         print("  python add-arrow.py diagram.excalidraw 300 200 500 300")
         print("  python add-arrow.py diagram.excalidraw 300 200 500 300 --label 'HTTP'")
         sys.exit(1)
-    
+
     diagram_path = Path(sys.argv[1])
     from_x = float(sys.argv[2])
     from_y = float(sys.argv[3])
     to_x = float(sys.argv[4])
     to_y = float(sys.argv[5])
-    
+
     # Parse optional arguments
     style = "solid"
     color = "#1e1e1e"
     label = None
     # Default: use edit suffix to avoid editor overwrite issues
     use_edit_suffix = True
-    
+
     i = 6
     while i < len(sys.argv):
         if sys.argv[i] == '--style':
@@ -296,12 +296,12 @@ def main():
         else:
             print(f"Error: Unknown option: {sys.argv[i]}")
             sys.exit(1)
-    
+
     # Validate inputs
     if not diagram_path.exists():
         print(f"Error: Diagram file not found: {diagram_path}")
         sys.exit(1)
-    
+
     try:
         work_path, final_path = prepare_edit_path(diagram_path, use_edit_suffix)
         add_arrow_to_diagram(work_path, from_x, from_y, to_x, to_y, style, color, label)

package/template/.trae/skills/excalidraw-diagram-generator/scripts/add-icon-to-diagram.py

@@ -37,60 +37,60 @@ def calculate_bounding_box(elements: List[Dict[str, Any]]) -> Tuple[float, float
     """Calculate the bounding box (min_x, min_y, max_x, max_y) of icon elements."""
     if not elements:
         return (0, 0, 0, 0)
-    
+
     min_x = float('inf')
     min_y = float('inf')
     max_x = float('-inf')
     max_y = float('-inf')
-    
+
     for element in elements:
         if 'x' in element and 'y' in element:
             x = element['x']
             y = element['y']
             width = element.get('width', 0)
             height = element.get('height', 0)
-            
+
             min_x = min(min_x, x)
             min_y = min(min_y, y)
             max_x = max(max_x, x + width)
             max_y = max(max_y, y + height)
-    
+
     return (min_x, min_y, max_x, max_y)
 
 
 def transform_icon_elements(
-    elements: List[Dict[str, Any]], 
-    target_x: float, 
+    elements: List[Dict[str, Any]],
+    target_x: float,
     target_y: float
 ) -> List[Dict[str, Any]]:
     """
     Transform icon elements to target coordinates with unique IDs.
-    
+
     Args:
         elements: Icon elements from JSON file
         target_x: Target X coordinate (top-left position)
         target_y: Target Y coordinate (top-left position)
-    
+
     Returns:
         Transformed elements with new coordinates and IDs
     """
     if not elements:
         return []
-    
+
     # Calculate bounding box
     min_x, min_y, max_x, max_y = calculate_bounding_box(elements)
-    
+
     # Calculate offset
     offset_x = target_x - min_x
     offset_y = target_y - min_y
-    
+
     # Create ID mapping: old_id -> new_id
     id_mapping = {}
     for element in elements:
         if 'id' in element:
             old_id = element['id']
             id_mapping[old_id] = generate_unique_id()
-    
+
     # Create group ID mapping
     group_id_mapping = {}
     for element in elements:
@@ -98,47 +98,47 @@ def transform_icon_elements(
             for old_group_id in element['groupIds']:
                 if old_group_id not in group_id_mapping:
                     group_id_mapping[old_group_id] = generate_unique_id()
-    
+
     # Transform elements
     transformed = []
     for element in elements:
         new_element = element.copy()
-        
+
         # Update coordinates
         if 'x' in new_element:
             new_element['x'] = new_element['x'] + offset_x
         if 'y' in new_element:
             new_element['y'] = new_element['y'] + offset_y
-        
+
         # Update ID
         if 'id' in new_element:
             new_element['id'] = id_mapping[new_element['id']]
-        
+
         # Update group IDs
         if 'groupIds' in new_element:
             new_element['groupIds'] = [
                 group_id_mapping[gid] for gid in new_element['groupIds']
             ]
-        
+
         # Update binding references if they exist
         if 'startBinding' in new_element and new_element['startBinding']:
             if 'elementId' in new_element['startBinding']:
                 old_id = new_element['startBinding']['elementId']
                 if old_id in id_mapping:
                     new_element['startBinding']['elementId'] = id_mapping[old_id]
-        
+
         if 'endBinding' in new_element and new_element['endBinding']:
             if 'elementId' in new_element['endBinding']:
                 old_id = new_element['endBinding']['elementId']
                 if old_id in id_mapping:
                     new_element['endBinding']['elementId'] = id_mapping[old_id]
-        
+
         # Update containerId if it exists
         if 'containerId' in new_element and new_element['containerId']:
             old_id = new_element['containerId']
             if old_id in id_mapping:
                 new_element['containerId'] = id_mapping[old_id]
-        
+
         # Update boundElements if they exist
         if 'boundElements' in new_element and new_element['boundElements']:
             new_bound_elements = []
@@ -149,31 +149,31 @@ def transform_icon_elements(
                         bound_elem['id'] = id_mapping[old_id]
                 new_bound_elements.append(bound_elem)
             new_element['boundElements'] = new_bound_elements
-        
+
         transformed.append(new_element)
-    
+
     return transformed
 
 
 def load_icon(icon_name: str, library_path: Path) -> List[Dict[str, Any]]:
     """
     Load icon elements from library.
-    
+
     Args:
         icon_name: Name of the icon (e.g., "EC2", "VPC")
         library_path: Path to the icon library directory
-    
+
     Returns:
         List of icon elements
     """
     icon_file = library_path / "icons" / f"{icon_name}.json"
-    
+
     if not icon_file.exists():
         raise FileNotFoundError(f"Icon file not found: {icon_file}")
-    
+
     with open(icon_file, 'r', encoding='utf-8') as f:
         icon_data = json.load(f)
-    
+
     return icon_data.get('elements', [])
 
 
@@ -216,12 +216,12 @@ def finalize_edit_path(work_path: Path, final_path: Path | None) -> None:
 def create_text_label(text: str, x: float, y: float) -> Dict[str, Any]:
     """
     Create a text label element.
-    
+
     Args:
         text: Label text
         x: X coordinate
         y: Y coordinate
-    
+
     Returns:
         Text element dictionary
     """
@@ -274,7 +274,7 @@ def add_icon_to_diagram(
 ) -> None:
     """
     Add an icon to an Excalidraw diagram.
-    
+
     Args:
         diagram_path: Path to the Excalidraw diagram file
         icon_name: Name of the icon to add
@@ -287,43 +287,43 @@ def add_icon_to_diagram(
     print(f"Loading icon: {icon_name}")
     icon_elements = load_icon(icon_name, library_path)
     print(f"  Loaded {len(icon_elements)} elements")
-    
+
     # Transform icon elements
     print(f"Transforming to position ({x}, {y})")
     transformed_elements = transform_icon_elements(icon_elements, x, y)
-    
+
     # Calculate icon bounding box for label positioning
     if label and transformed_elements:
         min_x, min_y, max_x, max_y = calculate_bounding_box(transformed_elements)
         icon_width = max_x - min_x
         icon_height = max_y - min_y
-        
+
         # Position label below icon, centered
         label_x = min_x + (icon_width / 2) - (len(label) * 5)
         label_y = max_y + 10
-        
+
         label_element = create_text_label(label, label_x, label_y)
         transformed_elements.append(label_element)
         print(f"  Added label: '{label}'")
-    
+
     # Load diagram
     print(f"Loading diagram: {diagram_path}")
     with open(diagram_path, 'r', encoding='utf-8') as f:
         diagram = json.load(f)
-    
+
     # Add transformed elements
     if 'elements' not in diagram:
         diagram['elements'] = []
-    
+
     original_count = len(diagram['elements'])
     diagram['elements'].extend(transformed_elements)
     print(f"  Added {len(transformed_elements)} elements (total: {original_count} -> {len(diagram['elements'])})")
-    
+
     # Save diagram
     print(f"Saving diagram")
     with open(diagram_path, 'w', encoding='utf-8') as f:
         json.dump(diagram, f, indent=2, ensure_ascii=False)
-    
+
     print(f"✓ Successfully added '{icon_name}' icon to diagram")
 
 
@@ -342,22 +342,22 @@ def main():
         print("  python add-icon-to-diagram.py diagram.excalidraw EC2 500 300")
         print("  python add-icon-to-diagram.py diagram.excalidraw EC2 500 300 --label 'Web Server'")
         sys.exit(1)
-    
+
     diagram_path = Path(sys.argv[1])
     icon_name = sys.argv[2]
     x = float(sys.argv[3])
     y = float(sys.argv[4])
-    
+
     # Default library path
     script_dir = Path(__file__).parent
     default_library_path = script_dir.parent / "libraries" / "aws-architecture-icons"
-    
+
     # Parse optional arguments
     library_path = default_library_path
     label = None
     # Default: use edit suffix to avoid editor overwrite issues
     use_edit_suffix = True
-    
+
     i = 5
     while i < len(sys.argv):
         if sys.argv[i] == '--library-path':
@@ -383,16 +383,16 @@ def main():
         else:
             print(f"Error: Unknown option: {sys.argv[i]}")
             sys.exit(1)
-    
+
     # Validate inputs
     if not diagram_path.exists():
         print(f"Error: Diagram file not found: {diagram_path}")
         sys.exit(1)
-    
+
     if not library_path.exists():
         print(f"Error: Library path not found: {library_path}")
         sys.exit(1)
-    
+
     try:
         work_path, final_path = prepare_edit_path(diagram_path, use_edit_suffix)
         add_icon_to_diagram(work_path, icon_name, x, y, library_path, label)
@@ -404,4 +404,3 @@ def main():
 
 if __name__ == '__main__':
     main()
-

package/template/.trae/skills/grill-me/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill Me"
+  short_description: "Sharpen a plan through interview"
+policy:
+  allow_implicit_invocation: false

package/template/.trae/skills/grill-with-docs/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill with Docs"
+  short_description: "Grill a design and write its docs"
+policy:
+  allow_implicit_invocation: false

package/template/.trae/skills/grilling/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: grilling
-description: Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
 ---
 
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
 Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
 
-If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
 
-Do not enact the plan until I confirm we have reached a shared understanding.
+Do not act on it until I confirm we have reached a shared understanding.

package/template/.trae/skills/grilling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Grilling"
+  short_description: "Stress-test thinking one question at a time"

package/template/.trae/skills/handoff/SKILL.md

@@ -9,7 +9,7 @@ Write a handoff document summarising the current conversation so a fresh agent c
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
 
-Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
 
 Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
 

package/template/.trae/skills/handoff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Handoff"
+  short_description: "Compact a conversation into a handoff"
+policy:
+  allow_implicit_invocation: false

package/template/.trae/skills/implement/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: implement
-description: "Implement a piece of work based on a PRD or set of issues."
+description: "Implement a piece of work based on a spec or set of tickets."
 disable-model-invocation: true
 ---
 
-Implement the work described by the user in the PRD or issues.
+Implement the work described by the user in the spec or tickets.
 
 Use /tdd where possible, at pre-agreed seams.
 

package/template/.trae/skills/implement/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Implement"
+  short_description: "Build work from a spec or tickets"
+policy:
+  allow_implicit_invocation: false

package/template/.trae/skills/improve-codebase-architecture/SKILL.md

@@ -17,6 +17,11 @@ This command is _informed_ by the project's domain model and built on a shared d
 
 ### 1. Explore
 
+**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
 Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
 
 Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
@@ -56,7 +61,7 @@ Do NOT propose interfaces yet. After the file is written, ask the user: "Which o
 
 ### 3. Grilling loop
 
-Once the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+Once the user picks a candidate, run the `/grilling` skill to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
 
 Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go: