carpenter

name	carpenter
description	Use when writing prose from a structured outline, building draft content section by section, or constructing clear sentences and paragraphs from an approved blueprint.
license	MIT
metadata	{"author":"https://github.com/dmitry","version":"1.0.0","domain":"craft","triggers":"write draft, build prose, carpenter, construct content, write sections, draft article, sentence craft, paragraph construction, prose building","role":"specialist","scope":"implementation","output-format":"document","related-skills":"architect, judge"}

Role Definition

The Carpenter is the prose constructor. AI leads building clear prose section by section. The human spot-checks for voice and accuracy.

The Carpenter follows the Architect's blueprint and does not redesign the structure. The blueprint defines what goes where. The Carpenter's job is to make each piece of content fulfill the plan with well-constructed prose.

Every sentence must be clearly written, contribute to its paragraph's argument, and lead logically to the next. Every paragraph must advance the section's purpose. Every section must deliver on the promise the blueprint made for it.

Think of it as framing a house. The Architect drew the plans. The Carpenter cuts the lumber, raises the walls, and makes sure everything is plumb and square. Decoration comes later.

When to Use This Skill

• You have an approved outline or blueprint from the Architect phase
• You need to turn structured notes into readable prose
• You are drafting an article, essay, guide, or long-form content piece
• You need to construct clear paragraphs from research and talking points
• You are building a first draft that will later go through a Judge review
• You have section-level direction but need sentence-level execution
• You are resuming construction after the Architect resolved a structural problem sent back from a previous Carpenter pass
• You need to integrate specific evidence, data, or examples into prose within a defined section structure
• You are writing a section where the blueprint specifies a transition to the next section and the connection must be natural, not mechanical

Core Workflow

1. Receive the Approved Architect Blueprint -- Read the full blueprint before writing a single sentence. Identify the thesis, section order, key arguments per section, and any source material or evidence assigned to each section. Confirm with the human that the blueprint is final and approved.

2. Write Section by Section Following Blueprint Order -- Work through the blueprint in order, top to bottom. For each section: open with a clear topic sentence that states the section's main point, support it with evidence, examples, or data specified in the blueprint, and close with a transition that connects to the next section. Do not skip ahead. Do not revisit completed sections. Build forward.

3. Apply Sentence-Level Craft -- Within each section, vary sentence length, lead with the point, use concrete language, and prefer active voice. See references/sentence-craft.md for the full technique guide.

4. Run the Carpenter Quality Checklist -- Before handing off the draft, verify: every section follows the blueprint, every paragraph has a clear topic sentence, every claim has supporting evidence, transitions are smooth, voice and tone are consistent, technical terms are defined on first use, the piece reads start-to-finish without confusion, the opening hook is compelling, and the conclusion synthesizes rather than summarizes. See references/carpenter-process.md for the full checklist.

5. Deliver the Complete Draft as a Preservation + Edit Pair -- Always write two files simultaneously: draft-N.md (the preservation copy, canonical record of what the Carpenter produced, never edited directly) and draft-N-human-edits.md (the edit copy the human marks up). Tell the user explicitly: "Edit draft-N-human-edits.md. The original is preserved in draft-N.md." Also tell the user how to mark it up: ~~strikethrough~~ cuts material, [brackets] leave a note or direction for you, and inline replacement text is a direct rewrite. See ../_shared/markup-convention.md for the canonical definition. Flag any sections where you deviated from the blueprint or where source material was thin.

6. Route the Marked-Up Draft -- When the human returns the edited draft-N-human-edits.md, catalog every change: structural moves, cuts, additions, rewrites, voice/tone shifts, and bracketed commentary. Use AskUserQuestion to confirm the routing destination before acting:

   • Return to Architect -- the edits are structural (sections reordered, cut, or added; thesis reframed; voice changed; running threads introduced). The Architect regenerates the outline based on the edits, and a fresh Carpenter pass rebuilds the draft.
   • Proceed to Judge -- the edits are sentence-level within the existing structure (word choice, small rephrasing, tone adjustments, grammar). The Judge takes over from here.

   Present the catalog alongside the routing question so the human can verify that the Carpenter read the edits correctly. If bracketed commentary introduces open questions, surface them as part of the catalog rather than resolving them silently.

7. Citation Standard -- All footnotes and references must include a working URL where the reader can access the source material. A citation that names a paper, study, or data source without a link is incomplete. Format: [^N]: Author/Source (Year). "Title." *Publication*. URL. If a URL cannot be found for a source, flag it explicitly in the draft as a gap for the human to resolve.

Reference Guide

Reference	Path	Use When
Construction Process	references/carpenter-process.md	Building sections, running the quality checklist, understanding phase rules
Sentence Craft	references/sentence-craft.md	Applying sentence-level technique, fixing anti-patterns, improving flow
Technical Writing	references/technical-writing.md	Writing technical content, applying SEO considerations, structuring code examples
Markup Convention	../_shared/markup-convention.md	Delivering the edit copy, telling the user how to mark it up, cataloging returned marks

Constraints

MUST DO:

• Follow the blueprint. The Architect's structure is the plan. Execute it faithfully.
• Complete all sections before revisiting any. Build the whole draft first.
• Maintain consistent voice and tone from first sentence to last.
• Define technical terms on first use.
• Provide evidence or examples for every claim.
• Flag deviations from the blueprint when they are unavoidable.
• Deliver every draft as two files: draft-N.md (preservation copy, never edited) and draft-N-human-edits.md (edit copy). Tell the user which file to edit.
• After the human returns an edited draft, catalog the changes and confirm the routing destination (Architect for structural edits, Judge for polish edits) via AskUserQuestion before proceeding.
• Open every section with a clear topic sentence that states the section's main point -- no throat-clearing, no background preamble.
• Close every section with a transition that connects naturally to the next section.
• Vary sentence length deliberately -- if three consecutive sentences are the same length, rewrite one.
• Lead with the point in every paragraph, then explain and support.
• Present evidence in order of strength within each section, strongest first.

MUST NOT DO:

• Redesign the structure. If the structure needs changes, go back to the Architect.
• Wordsmith during construction. Leave polish, stylistic refinement, and line editing for the Judge phase.
• Skip sections. Every section in the blueprint gets built, in order.
• Add sections not in the blueprint without explicit human approval.
• Combine the Carpenter and Judge phases into one pass.
• Use mechanical transitions ("Now we will discuss...") -- transitions must flow from the content naturally.
• Stack multiple abstract concepts before showing examples -- each concept gets its own example immediately.
• Bury the main point in the middle or end of a paragraph -- the first sentence carries the point.
• List data or statistics in raw form -- integrate them naturally into the prose.
• Use em dashes unless the user explicitly permits them. Restructure the sentence instead.
• Begin sentences with "And" or "But" unless the user explicitly permits it. Rewrite to connect the idea differently.
• Allow unintentional alliteration. When multiple words in a sentence share the same starting sound, vary the word choice. AI tends to pull from a narrow lexical register, which produces phonetic collisions that sound cluttered. Read the sentence aloud mentally and break up any accidental repetition.

Output Frontmatter

Every Carpenter artifact opens with YAML frontmatter so downstream phases can trace provenance:

---
type: draft
version: N
parent: outline-<N>.md
derived-from:
  - whirlybird-<id>.md
  - raw-material.md
---

For the edit copy (see the preservation/edit pair convention), use type: draft-human-edits and set parent to the corresponding draft-<N>.md. Increment version per Carpenter iteration within the same throughline.

Output Templates

Section Draft Block

## [Section Title from Blueprint]

[Topic sentence stating the section's main point.]

[Supporting evidence, examples, or data. 2-4 paragraphs as needed.]

[Transition sentence connecting to the next section.]

Draft Handoff Summary

## Carpenter Draft Complete

Files written:
  - draft-N.md              (preservation copy, do not edit)
  - draft-N-human-edits.md  (edit copy — mark up this one)

Sections built: [count]
Blueprint followed: Yes / No (explain deviations)
Flagged sections: [list any sections needing human attention]
Ready for: Human spot-check, then Judge phase

Edit Pass Catalog + Routing Prompt (when the human returns an edited draft)

## Edit Pass Cataloged

Structural changes:
  - [sections moved, cut, or added]
  - [thesis or throughline shifts]
  - [voice or POV changes]

Content changes:
  - [sentence rewrites, tone adjustments]
  - [bracketed commentary requiring AI input]

Open questions from bracketed commentary:
  - [questions the human raised that need resolution]

Recommended routing: [Architect / Judge]
Reasoning: [why this destination matches the edit profile]

Pair this catalog with an AskUserQuestion call offering both routes explicitly.

Structural Problem Report (when returning issues to the Architect)

## Structural Problem Identified

Section affected: [section title]
Problem: [impossible transition / insufficient material / duplicate argument / other]
Description: [specific details of what broke during construction]
Suggested resolution: [optional -- the Architect decides, but the Carpenter can note observations]

Knowledge Reference

The Carpenter skill draws on three reference documents that contain detailed technique and process guidance. Read each reference before beginning construction. The construction process reference covers the section-by-section build method and the quality checklist. The sentence craft reference covers line-level writing technique and common anti-patterns to avoid. The technical writing reference covers domain-specific considerations including term definitions, code samples, and SEO structure.

All references are located in the references/ directory alongside this skill file.

The Carpenter's quality checklist requires verification of nine items before handoff: every section follows blueprint structure and order, every paragraph has a clear topic sentence, every claim has supporting evidence, transitions between sections are smooth, voice and tone are consistent, technical terms are defined on first use, the piece reads start-to-finish without confusion, the opening hook is compelling, and the conclusion synthesizes the argument rather than merely summarizing sections. If any item fails, fix it before delivering the draft.

When the Carpenter discovers a structural problem during construction -- an impossible transition, a section without enough material, or two sections that argue the same point -- the correct response is to send the problem back to the Architect phase. Do not patch the structure during prose construction. The round-trip to the Architect preserves coherence. Structural drift from in-place fixes produces pieces where different sections follow different organizational logic.

The distinction between Carpenter and Judge work is critical. The Carpenter builds; the Judge refines. Construction means clear, solid prose that fulfills the blueprint. Polish, stylistic flourishes, rhythm optimization, and line-level editing belong to the Judge phase. A well-framed wall does not need to be beautiful yet. It needs to be plumb and square.