from-things-mmw

What this skill does

<references>
  <reference name="things-bridge" path="references/things-bridge.md" />
  <reference name="media-guide" path="../add-media/references/media-guide.md" />
</references>

<purpose>
Source a blog post from one or more i-did-a-thing evidence logs. Each log already contains a Blog Seed, narrative structure, and potential angles -- this skill transforms them into engaging posts.
</purpose>

<steps>

  <step id="load-config" number="1">
    <description>Load Configuration</description>

    <load-config>
      <action>Resolve the user's home directory.</action>
      <command language="bash" output="home" tool="Bash">echo $HOME</command>
      <constraint>Never pass `~` to the Read tool.</constraint>

      <read path="<home>/.things/config.json" output="config" />
      <if condition="config-missing">Tell the user: "Run `/things:setup-things` first." Then stop.</if>

      <read path="<home>/.things/mark-my-words/preferences.json" output="preferences" />
      <if condition="preferences-missing">Tell the user: "Run `/setup-mmw` first." Then stop.</if>
    </load-config>

    <action>Read `platform` from preferences.json (default to `quartz` if not set). Read the platform template from `../../platforms/<platform>.md` (relative to this skill's directory). This template defines all platform-specific formatting rules -- frontmatter fields, content syntax, image format, callouts, code blocks, and file naming conventions.</action>

    <action>Load voice profile.</action>
    <if condition="default-voice-set">
      <read path="<home>/.things/mark-my-words/voices/<default_voice>.md" output="voice" />
      <if condition="voice-file-missing">Warn the user that their default voice profile is missing and continue without a voice.</if>
    </if>
    <action>Also check if any voice profiles exist in `<home>/.things/mark-my-words/voices/` using Glob. Store this for the interview step.</action>

    <action>Load professional profile.</action>
    <read path="<home>/.things/shared/professional-profile.json" output="professional-profile" />
    <if condition="professional-profile-missing">Fall back to `author_name` from config.json.</if>

    <action>Resolve media directory.</action>
    <if condition="media-dir-set">Resolve the full media path as `<content_root>/<media_dir>` and ensure the directory exists (`mkdir -p`). Store this path for use in visual planning and post generation.</if>
  </step>

  <step id="resolve-content-location" number="2">
    <description>Resolve Content Location</description>

    <if condition="source-type-remote">
      <action>Check if the repo is already cloned at `<workdir>` (read `workdir` from preferences.json, default `<home>/.mark-my-words`).</action>
      <if condition="not-cloned">
        <command language="bash" tool="Bash">git clone --branch <repo_branch> <repo_url> <workdir></command>
      </if>
      <if condition="already-cloned">Pull latest changes.</if>
      The content root is `<workdir>/<content_dir>/`.
    </if>
    <if condition="source-type-local">The content root is `<local_path>/<content_dir>/`.</if>
  </step>

  <step id="select-logs" number="3">
    <description>Select Logs</description>

    <action>Read `<home>/.things/i-did-a-thing/index.json` to get the full index of all logs with their metadata, blog seeds, and blog_potential ratings.</action>

    <if condition="arguments-provided">Find matching entries in the index.</if>
    <if condition="no-arguments">
      <ask-user-question>
        <question>What do you want to write about?</question>
        <option>Browse recent logs (last 10)</option>
        <option>Search by tag or skill</option>
        <option>Find entries marked high blog potential</option>
        <option>Combine multiple logs into one post</option>
      </ask-user-question>
    </if>

    <if condition="user-browse-recent">Show the first 10 entries from `index.json` (already sorted by date descending) with title, date, impact, and `blog_potential`. Let the user select one.</if>
    <if condition="user-search">Ask for search criteria (tag, skill, or keyword). Filter entries in `index.json` by matching tags, skills_used, or title/description. Present matching results and let the user select.</if>
    <if condition="user-high-blog-potential">Filter entries in `index.json` where `blog_potential` is `"high"`. Present results.</if>
    <if condition="user-combine-multiple">Let the user select 2-5 logs to weave into a single narrative post. See <reference name="things-bridge"/> for multi-log strategies.</if>
  </step>

  <step id="read-selected-logs" number="4">
    <description>Read Selected Logs</description>

    <action>Read the full content of selected log(s). Extract:</action>
    - Blog Seed section -- the opening hook
    - Potential angles -- narrative direction options
    - Context / Action / Result -- the substance
    - Reflection -- personal voice and takeaway
    - Metrics -- concrete numbers from frontmatter
    - Tags and skills -- for post categorization
  </step>

  <step id="choose-narrative-angle" number="5">
    <description>Choose the Narrative Angle</description>

    <ask-user-question>
      <question>What angle should this post take?</question>
      Present the potential angles from the log(s), plus standard options:
      <option><Angle 1 from log's "Potential angles"></option>
      <option><Angle 2 from log's "Potential angles"></option>
      <option>Tutorial/how-to (teach what you learned)</option>
      <option>Retrospective (reflect on the journey)</option>
    </ask-user-question>
  </step>

  <step id="select-voice" number="6">
    <description>Select Voice</description>

    <if condition="voice-profiles-exist">
      <if condition="default-voice-set">Show it and ask if they want to use it, pick a different one, or skip voice for this post.</if>
      <if condition="no-default-voice">List available voices and let them pick one or skip.</if>
    </if>
  </step>

  <step id="scan-existing-posts" number="7">
    <description>Scan Existing Posts</description>

    <action>Use Glob and Grep to scan the blog content directory:</action>
    - Find all `.md` files in the target subdirectory
    - Extract existing tags from frontmatter across posts
    - This informs tag suggestions and maintains consistency
  </step>

  <step id="plan-visuals" number="7.5">
    <description>Plan Visuals</description>

    <constraint>Only run this step if `media_dir` is configured.</constraint>

    <action>Analyze the selected log(s) for visual content opportunities:</action>
    <validate name="architecture">Architecture in Action section -- flowcharts or system diagrams (only if platform supports Mermaid)</validate>
    <validate name="process-flows">Process flows (deployment pipelines, workflows, data flows) -- sequence diagrams or flowcharts</validate>
    <validate name="comparisons">Before/after comparisons -- side-by-side images or diagrams</validate>
    <validate name="metrics">Metrics and results -- tables or formatted data presentations</validate>

    <ask-user-question>
      <question>How should we handle visuals?</question>
      <option>Generate diagrams where they fit -- create Mermaid diagrams for architecture and flow content (only offered if platform supports Mermaid)</option>
      <option>Also find relevant images -- diagrams plus web-searched images for visual concepts</option>
      <option>Keep it text-only -- skip visuals entirely</option>
      <option>Decide as we write -- suggest visuals inline during generation</option>
    </ask-user-question>

    <action>Store the user's choice for Step 8.</action>
  </step>

  <step id="generate-post" number="8">
    <description>Generate the Post</description>

    <action>Transform the log into a blog post following the platform template loaded in Step 1 and the transformation guide in <reference name="things-bridge"/>.</action>

    <constraint name="transformation-rules">
      1. Open with the Bl