rpi/.claude/skills/create-structure-outline/SKILL.md

name	description
create-structure-outline	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

## 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:

# 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.