---
name: code-submit
description: Creates a GitHub draft PR for completed work and generates a polished HTML submission report that fully explains the changes end to end. Use when the user wants implementation plus a submission artifact with visuals, architecture context, screenshots or recordings when relevant, and explanations of non-obvious code in the larger codebase.
---

# code-submit

Use this skill when the user wants work delivered as both:
1. a **GitHub draft PR**, and
2. a **self-contained HTML submission artifact** that explains the changes without requiring the reviewer to navigate elsewhere.

The report may reference local files such as screenshots or videos, but the HTML itself must contain enough explanation, context, and visuals that a reviewer can understand the change from that single page.

## Outcome

For each invocation, produce all of the following unless the user explicitly narrows scope:

- code changes requested by the user
- a local branch for the change
- at least one commit with a clear message
- a **draft GitHub PR** opened with `gh pr create --draft`
- a polished HTML report at `.submissions/<change-slug>.html`, where `<change-slug>` is derived from the task title
- a concise final summary containing:
  - branch name
  - commit hash
  - PR URL
  - report path
  - test/lint results
  - notable risks or follow-ups

## Required behavior

### 0) Derive `<change-slug>` from the task title

Create `<change-slug>` from the task title, not from the branch name.

Slug rules:

- start from the task title or a concise restatement of it when necessary
- lowercase it
- replace spaces and punctuation with hyphens
- collapse repeated hyphens
- trim leading/trailing hyphens
- keep it reasonably short but descriptive

Examples:

- `Add OAuth device flow` -> `add-oauth-device-flow`
- `Fix flaky cache invalidation in worker retries` -> `fix-flaky-cache-invalidation-in-worker-retries`

Use the same `<change-slug>` consistently for:

- `.submissions/<change-slug>.html`
- `.submissions/<change-slug>-assets/`
- `.submissions/<change-slug>.pr.md`

## Required behavior

### 1) Implement first, narrate second

First complete the actual code changes. Do not generate the report before the implementation is stable enough to describe.

### 2) Always build reviewer context

The submission HTML must explain:

- what changed
- why the change was needed
- how the new behavior works end to end
- where the change fits in the codebase
- which files/modules were touched and why
- non-obvious logic, tradeoffs, edge cases, or constraints
- validation performed
- known limitations or follow-ups

### 3) Open a draft PR on GitHub

Use GitHub only. Prefer `gh` CLI.

PR title alignment rules:

- use the task title as the starting point for the PR title
- keep the PR title semantically aligned with the task title even if you shorten or polish it
- avoid introducing a different framing in the PR title than in the task title
- keep the task title, PR title, branch name, and `<change-slug>` obviously related

Recommended naming alignment:

- task title: human-readable source of truth
- PR title: polished version of the task title
- branch name: a concise git-safe variant, typically prefixed like `feat/`, `fix/`, or `chore/` when appropriate
- `<change-slug>`: slugified task title used for submission files

Typical flow:

```bash
git status --short
git checkout -b <branch-name>
# make changes
# run checks
git add <files>
git commit -m "<clear message>"
gh pr create --draft --title "<title>" --body-file <temp-pr-body-file>
```

If the branch already exists, reuse it when appropriate. If `gh` is unavailable or auth fails, clearly report the blocker and still prepare the PR title/body locally.

### 4) Run validation, but do not block on it

Run tests and lint **when configured in the repo**.

- If they pass: include results in PR and HTML.
- If they fail: still create the draft PR unless a repo policy explicitly forbids it.
- Always summarize failures clearly and include likely cause / next step when possible.

### 5) Include visuals whenever they make sense

The report should include as many relevant visuals as possible:

- file tree of impacted areas
- codebase fit / architecture map
- before/after behavior
- request/data/control flow diagrams
- dependency or module relationship diagrams
- per-file diff summaries
- screenshots when there is UI output
- screen recordings or GIF/video embeds when there is an interactive flow worth showing
- terminal transcripts or annotated command outputs when the change is CLI/backend only

If a visual is not practical, replace it with a clear diagram or structured explanation. Do not silently omit categories without explanation.

## Report quality bar

The HTML should feel clean, modern, and easy to scan. Optimize for a reviewer skimming quickly and then drilling deeper.

### Design principles

- clear hierarchy
- compact summaries first, details on demand below
- use cards, callouts, tables, and diagrams
- syntax-highlighted code snippets when helpful
- avoid walls of text
- make important conclusions visually obvious

### Minimum report sections

Create these sections in `.submissions/<change-slug>.html` unless the task truly does not need one:

1. **Header**
   - title
   - repo/project name
   - date/time
   - author/agent
   - branch
   - commit
   - PR link

2. **Executive Summary**
   - short explanation of the change
   - user problem solved
   - top-level implementation approach

3. **What Changed**
   - grouped list of changed files
   - per-file purpose
   - concise diff summary

4. **How It Works End to End**
   - numbered flow from trigger/input to result/output
   - request lifecycle, data flow, or user journey

5. **Codebase Fit**
   - where the touched code sits in the larger architecture
   - neighboring modules/services/components and their roles
   - why this location is the right one

6. **Visualizations**
   - architecture diagram
   - flow diagram
   - impacted file tree
   - screenshots / recordings / terminal evidence as relevant

7. **Non-Obvious Parts Explained**
   - tricky logic
   - hidden coupling
   - invariants
   - edge cases
   - constraints and tradeoffs

8. **Validation**
   - tests run
   - lint/format run
   - manual verification
   - failures/non-blocking warnings

9. **Risks and Follow-Ups**
   - known limitations
   - monitoring concerns
   - suggested next steps

10. **Appendix**
   - selected code snippets
   - commands used
   - environment notes if relevant

## How to gather material for the report

After implementation, collect evidence from the repo and your changes.

### Use repository exploration

Gather:

- touched file list from `git diff --name-only`
- diff stats from `git diff --stat`
- code snippets from important files
- test and lint output
- architecture clues from repo structure and imports
- screenshots or recordings when the project has a UI or visible workflow

### For screenshots and recordings

If the project has a runnable UI or browser experience and it is practical in the environment:

- capture representative before/after screens or post-change screens
- capture a short recording/GIF for interactive flows
- embed them in the HTML with explanatory captions

If capture is impractical, state why and substitute:

- storyboard frames
- sequence diagrams
- terminal walkthrough
- static annotated screenshots of generated output

### For non-obvious code

Do not only explain the changed function. Explain how it relates to:

- upstream callers
- downstream consumers
- shared utilities or data contracts
- architectural boundaries
- any pre-existing patterns the code follows or intentionally breaks

## Draft PR requirements

The PR body should be consistent with the HTML report, but shorter.

Include:

- summary
- changed areas
- validation results
- risks/follow-ups
- link/path to `.submissions/<change-slug>.html`

Suggested structure:

```md
## Summary
- ...

## Changes
- ...

## Validation
- ...

## Risks / Follow-ups
- ...

## Submission Artifact
- `.submissions/<change-slug>.html`
```

## Recommended workflow

1. Read the task and inspect the repo.
2. Implement the requested changes.
3. Run available tests/lint/verification.
4. Gather evidence for the report.
5. Generate `.submissions/<change-slug>.html`.
6. Create branch if needed.
7. Commit changes.
8. Prepare PR title/body.
9. Open draft PR with `gh`.
10. Return a concise summary with paths and links.

When possible, keep these aligned:

- task title
- PR title
- branch name
- `.submissions/<change-slug>.html`

## HTML implementation guidance

Prefer a single HTML file with embedded CSS and lightweight JS.

The HTML may reference local media files, but the explanatory content must live in the HTML itself. A reviewer should not need to open source files, PR comments, or external docs to understand the change.

Include:

- sticky table of contents
- expandable details sections for dense material
- SVG or Mermaid-rendered diagrams when useful
- clearly labeled screenshots/recordings
- code excerpts with filenames and commentary
- visual status badges for pass/fail/warn items

## File conventions

Preferred output locations:

- Report: `.submissions/<change-slug>.html`
- Supporting media: `.submissions/<change-slug>-assets/`
- Draft PR body scratch file: `.submissions/<change-slug>.pr.md`

Derive `<change-slug>` from the task title and keep it stable across all generated files for that task.

If the repo already has a better artifact location, follow existing conventions and note the path.

## If tooling is missing

- No tests configured: say so explicitly in the report and PR.
- No lint configured: say so explicitly.
- No `gh`: generate branch/commit and write `.submissions/<change-slug>.pr.md` with the exact `gh pr create` command the user can run.
- No UI runtime or screenshot tooling: replace with diagrams and clearly state the limitation.

## Browsing submissions in the TUI

This project includes a project-local Pi extension with a `/submissions` command.

Use it to browse generated submission reports from the terminal UI:

- `/submissions` opens a browser TUI for HTML files in `.submissions/`
- `/submissions <dir>` opens the same browser TUI for HTML files under the given directory
- the TUI shows a file list plus a preview pane with extracted title, headings, and summary text
- selecting an entry opens that HTML file in the system browser

Prefer this command when the user wants to review or demo previously generated submission artifacts.

## Read next

Before using this skill, read these references:

- [Workflow checklist](references/workflow-checklist.md)
- [HTML report blueprint](references/html-report-blueprint.md)
- [PR body template](references/pr-template.md)