zudoesa-articlify

# Articlify for esa

Convert the current conversation into an esa article by crafting a detailed writing brief and delegating to the `zudoesa-writer` subagent.

## Argument: `--conversation`

When `$ARGUMENTS` contains `--conversation`, the article must preserve the actual
conversation as-is. This means:

- **NEVER summarize the conversation.** Reproduce the actual dialogue flow faithfully.
- **Keep casual utterances.** Words like 「なるほど」「ふーん」「どう思う？」「OK」

  「hum...」are meaningful conversational texture — they make the article sound
  natural and human. Removing them makes it look AI-auto-written.

- **Minimal rewriting only.** Typo fixes and light formatting are OK. Do NOT

  restructure, condense, or rephrase the user's words beyond that.

- **PRESERVE THE ORIGINAL LANGUAGE. DO NOT TRANSLATE.** This is critical. If the

  conversation was in English, keep it in English. If it was in Japanese, keep it
  in Japanese. If it was mixed, keep both languages as-is. Translating the
  conversation to Japanese destroys the original text — it is a total loss of the
  source material the user wanted to preserve. The whole point of `--conversation`
  is to capture the raw dialogue, and translation defeats that purpose. The
  surrounding frontmatter `title` and any minimal scaffolding headings MAY be in
  Japanese, but the conversation body itself must remain in its original language.

- **Include the brief in the writing prompt** with explicit instruction:

  "This is a conversation-style article with `--conversation` mode. Preserve the
  dialogue verbatim IN THE ORIGINAL LANGUAGE. Only fix typos and apply vocabulary
  rules. Do NOT summarize, restructure, or translate. If the conversation is in
  English, the article body must remain in English."

## Workflow

### Step 1: Gather context from conversation

Review the conversation history and identify:

- What topic was discussed
- What was tried (approaches A, B, C...)
- What worked and what didn't
- Key technical details, code snippets, commands
- The conclusion or final approach taken
- Any opinions or insights expressed
- **Images**: Any images attached to the conversation (screenshots, diagrams, etc.)

### Step 1.5: Handle images (if any)

If images were provided in the conversation (attached screenshots, diagrams, etc.):

1. **Determine the article slug** from the topic (e.g., `20260209-package-json-organization`)
2. **Create the image directory** in the esa repo:

   ```
   mkdir -p $HOME/repos/w/esa/doc/public/img/articles/YYYYMMDD-slug/
   ```

3. **Copy each image** to that directory with a descriptive filename:

   ```
   cp /path/to/source/image.png $HOME/repos/w/esa/doc/public/img/articles/YYYYMMDD-slug/descriptive-name.png
   ```

4. **Record the image paths** for the writing brief. The markdown reference format is:

   ```
   ![alt text](/img/articles/YYYYMMDD-slug/descriptive-name.png)
   ```

### Step 2: Craft the writing brief

Create a **detailed, self-contained prompt** that the writer subagent can use without any conversation context. The brief must include:

1. **Article topic**: Clear one-line description
2. **Background**: Why this was done, what motivated it
3. **Story arc**: The journey (tried X, it failed because Y, then tried Z which worked)
4. **Technical details**: Specific code, commands, configurations, error messages
5. **Key points to cover**: Bullet list of must-include content
6. **Images**: If images were copied in Step 1.5, list each with its markdown path and a description of what it shows and where it should be placed in the article
7. **Conclusion**: What was the outcome, what was learned
8. **Tone guidance**: Any specific angle or framing (if applicable)

The brief should be written so that someone with zero context could write the full article from it alone.

### Step 3: Delegate to subagent

Use the Agent tool to spawn the `zudoesa-writer` subagent with `run_in_background: true` so the user is not blocked during writing:

```
Agent tool:
  subagent_type: zudoesa-writer
  run_in_background: true
  prompt: [the detailed writing brief from Step 2]
```

The subagent will:

- Read the repo's writing style guides
- Write the article following esa conventions (in Japanese by default, but preserving the original language when `--conversation` is specified)
- Set `sidebar_position` using the formula `999999999999 - YYYYMMDDHHMM` (ensures newest articles appear first)
- Save to the articles directory
- Run formatting checks

### Step 4: Verify sidebar_position

After the subagent completes, read the created article file and verify that:

- `sidebar_position` is present in the frontmatter
- The value follows the formula `999999999999 - YYYYMMDDHHMM`

If `sidebar_position` is missing or incorrect, fix it directly. This is critical — without it, the article appears at the bottom of the sidebar instead of the top.

### Step 5: Report back

After the subagent completes, report:

- The file path of the created article
- A brief summary of what was written

## Important Notes

- The writing brief is the ONLY context the subagent receives - make it thorough
- Include actual code snippets, error messages, and command outputs in the brief
- If the conversation involved multiple topics, ask the user which one to articlify
- **Images must be copied BEFORE delegating** - the subagent cannot see conversation images
- Include the full markdown image reference paths in the brief so the subagent can embed them
- $ARGUMENTS can provide additional guidance on focus or angle