---
name: create-structure-outline
description: create a phased implementation plan based on research and design decisions
---

# Create Structure Outline

You are creating a phased implementation plan based on research findings and design decisions.

## Input

- `changeRequest`: The user's original change request
- `researchDocumentPath`: Path to the research document (e.g., `.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-research.md`)
- `designDecisions`: List of design decisions made during the design discussion phase
- `patternsToFollow`: List of patterns identified during research

## Steps

1. **Read all input documents FULLY**:
   - Use Read tool WITHOUT limit/offset to read the research document
   - Understand the current state of the codebase from research findings
   - Review all design decisions and patterns to follow

2. **Check for related task content**:
   - If a path in `.humanlayer/tasks/TASKNAME` is mentioned, use `ls .humanlayer/tasks/TASKNAME`
   - Read all relevant files in the task directory
   - Read relevant files mentioned in the task files

3. **Spawn sub-agents for follow-up research**:

   **For deeper investigation:**
   - **codebase-locator**: Find additional files if needed
   - **codebase-analyzer**: Deep-dive on specific implementations
   - **codebase-pattern-finder**: Find more examples of patterns
   - **web-search-researcher**: Research external best practices

   Do not run agents in the background - FOREGROUND AGENTS ONLY.

4. **Create a phased implementation plan**:
   - Break the work into logical phases
   - Each phase should be independently testable
   - Order phases vertically rather than horizontally - wire everything together in a testable way and then add functionality incrementally

5. **For each phase, specify**:
   - Overview of what's being built
   - Specific file changes with descriptions
   - Validation approach - how we'll manually verify the phase works

6. **Document what's out of scope**:
   - What we're NOT doing in this plan
   - Future enhancements to consider later


## Output Document

1. **Read the structure outline template**

`Read({SKILLBASE}/references/structure_outline_template.md)`

2. **Write the structure outline** to `.humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-structure-outline.md`
   - First, find the task directory: `ls .humanlayer/tasks | grep -i "eng-XXXX"`
   - If the directory doesn't exist, create: `.humanlayer/tasks/ENG-XXXX-description/`
   - Format: `YYYY-MM-DD-structure-outline.md` where YYYY-MM-DD is today's date
   - Directory naming:
     - With ticket: `.humanlayer/tasks/ENG-1478-parent-child-tracking/2025-01-08-structure-outline.md`
     - Without ticket: `.humanlayer/tasks/improve-error-handling/2025-01-08-structure-outline.md`

3. **Read the final output template**

`Read({SKILLBASE}/references/structure_outline_final_answer.md)`

4. Respond to the user with a summary following the template, including GitHub permalinks

## Work with the user to iterate on the design

3. **If the user gives any input along the way**:
   - DO NOT just accept the correction
   - Spawn new research tasks to verify the correct information
   - Read the specific files/directories they mention
   - Only proceed once you've verified the facts yourself
   - interpret ALL user feedback as instructions to update the document, not to begin implementation
   - Update the structure according to the user's feedback

<guidance>
## Cloud Permalinks

When you write or edit documents in .humanlayer/tasks/, a cloud permalink is automatically provided in the hook response.
- The permalink appears as `additionalContext` after Write/Edit/MultiEdit operations
- Use this permalink in your final output for easy navigation
- Example format: `http(s)://{DOMAIN}/artifacts/{artifactId}`

## Markdown Formatting

When writing markdown files that contain code blocks showing other markdown (like README examples or SKILL.md templates), use 4 backticks (````) for the outer fence so inner 3-backtick code blocks don't prematurely close it:

````markdown
# Example README
## Installation
```bash
npm install example
```
````

## Phase Validation Design

Not every phase requires manual validation, don't put steps for manual validation just to have them. 

There's a good chance that if a phase cannot be manually checked, the phase is either too small
or not vertical enough. The goal of manual validation is to avoid getting to the end of a 1000+ line
code change and then having to figure out which part went wrong.

Automated testing is always better than manual testing - be thoughtful based on your knowledge 
of the codebase and testing patterns.

</guidance>