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

name	description
iterate-structure-outline	iterate on structure outline based on user feedback. if given a path to a document in .humanlayer/tasks/*/*-structure-outline.md, use this skill.

Iterate Structure Outline

You are iterating on an existing structure outline document based on user feedback.

Input

• docPath: Path to the existing structure outline document (e.g., .humanlayer/tasks/ENG-XXXX-description/YYYY-MM-DD-structure-outline.md)
• Optionally, a ticket file path containing comments with feedback

Initial Check

If the user calls this with no instructions or feedback, ask them for their feedback:

I'm ready to iterate on the structure outline. What feedback or changes would you like me to incorporate? For example:
- Phase reorganization
- Scope changes (add/remove items)
- Answers to open questions
- Additional context or requirements

Then wait for the user's feedback before proceeding.

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. If the user gives any input:

   • DO NOT just accept the correction blindly
   • Spawn research tasks to verify the information if needed
   • Read the specific files/directories they mention
   • Only proceed once you've verified the facts yourself

4. Spawn sub-agents for follow-up research (if needed):

   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.

5. Process the feedback:

   • If user requested phase changes: Reorganize phases as requested
   • If user requested scope changes: Update "What we're not doing" and phase contents
   • If user answered open questions: Remove from open questions and incorporate into plan
   • Keep the same YAML frontmatter and format

6. Update document (if changes needed):

   • Update the document at the same docPath
   • Reorganize phases as needed
   • Update file changes within phases
   • Update validation approaches
   • Remove answered questions from "Open Questions"

7. Update the user

   • Read the final output template: Read({SKILLBASE}/references/structure_outline_final_answer.md)
   • Respond with a summary following the template, including GitHub permalinks.

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