Carpenter

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`." 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

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.

Carpenter Construction Process

This reference defines the section-by-section construction method, the quality checklist, and the phase rules that govern the Carpenter's work.

Section-by-Section Construction

Work through the blueprint in strict order. Each section follows the same construction pattern.

Opening: Topic Sentence

Open every section with a clear topic sentence that states the section's main point. The reader should know what the section is about after the first sentence. Do not open with background, context, or throat-clearing. State the point, then support it.

Strong opening: "Caching reduces database load by serving repeated queries from memory."

Weak opening: "When we think about performance, there are many factors to consider, and one of them is how we handle repeated requests."

Middle: Evidence and Support

After the topic sentence, support the claim with evidence, examples, or data drawn from the blueprint. The blueprint specifies what source material belongs in each section. Use it.

• Present evidence in order of strength. Lead with the most compelling point.
• Use concrete examples immediately after abstract claims.
• If the blueprint assigns data or statistics to a section, integrate them naturally into the prose rather than listing them.
• Keep paragraphs focused. One idea per paragraph. If a paragraph makes two points, split it.

Closing: Transition

Close every section with a sentence that connects its content to the next section. The transition should feel natural, not mechanical. The end of one section should make the reader want to continue to the next.

Natural transition: "With the data model in place, the next decision is how the API exposes it."

Mechanical transition: "Now we will discuss the API layer."

Maintaining Voice and Tone

Consistency matters more than perfection. Choose a voice at the start and hold it throughout.

• Match the voice to the audience specified in the blueprint.
• If the blueprint does not specify voice, default to clear, direct, and professional.
• Avoid shifting between formal and casual within the same piece.
• Read the draft aloud (or simulate reading aloud) to catch tonal shifts.

Carpenter Quality Checklist

Run this checklist against the complete draft before handoff. Every item must pass.

• [ ] Every section follows the blueprint structure and order
• [ ] Every paragraph has a clear topic sentence
• [ ] Every claim has supporting evidence or a concrete example
• [ ] Transitions between sections are smooth and logical
• [ ] Voice and tone are consistent from start to finish
• [ ] Technical terms are defined on first use
• [ ] The piece can be read start-to-finish without confusion
• [ ] The opening hook is compelling and draws the reader in
• [ ] The conclusion synthesizes the argument rather than merely summarizing the sections

If any item fails, fix it before delivering the draft.

Phase Rules

These rules define what the Carpenter does and does not do. They protect the integrity of the multi-phase writing process.

Follow the blueprint. The Architect's structure is the contract. The Carpenter executes it. If a section feels wrong or out of order, flag it for the human rather than rearranging on your own. Structural changes require going back to the Architect phase.

Write, do not edit. The Carpenter's job is construction, not decoration. Write clear, solid prose. Do not spend time on stylistic flourishes, word-level polish, or rhythm optimization. That work belongs to the Judge phase. A well-framed wall does not need to be beautiful. It needs to be plumb and square.

Build the whole house before decorating. Complete every section in the blueprint before returning to revise any section. Forward momentum matters. A half-built draft with one polished section is worse than a complete draft with rough edges. The Judge will smooth those edges.

Leave polish for the Judge. Resist the temptation to line-edit as you draft. If you notice an awkward sentence, leave it and keep building. Mark it if you must, but do not stop construction to fix it. The Judge phase exists precisely for this work.

Sentence Craft Reference

This reference covers sentence-level writing technique for the Carpenter phase. These are construction fundamentals, not stylistic preferences. Apply them consistently.

Vary Sentence Length

Monotonous sentence length puts readers to sleep. Mix short declarative sentences with longer explanatory ones. Short sentences punch. Long sentences develop ideas, connect concepts, and carry the reader through complex reasoning. The contrast between them creates rhythm.

A paragraph of all short sentences feels choppy and breathless. A paragraph of all long sentences feels dense and exhausting. Alternate deliberately.

Rule of thumb: If three consecutive sentences are the same length, rewrite one.

Lead with the Point

State the point first. Then explain, support, and qualify. Readers scan. If the point is buried in the middle or end of a paragraph, scanners miss it and careful readers waste effort finding it.

Point-first: "Active voice makes prose clearer. The subject acts on the object, which gives the reader a direct line from actor to action to result."

Buried lede: "When we consider the various ways that sentences can be constructed, and we look at the relationship between subject and object, we find that active voice, where the subject acts on the object, tends to produce clearer prose."

The second version makes the reader work to find the point. The first version delivers it immediately and then explains why.

Use Concrete Language

Abstract language obscures meaning. Concrete language reveals it. Replace vague terms with specific ones whenever possible.

Abstract: "The system experienced degraded performance under high utilization conditions."

Concrete: "Response times doubled when the server hit 80% CPU usage."

The concrete version tells the reader exactly what happened. The abstract version tells them something happened but leaves the details unclear.

Concrete language also builds credibility. Specifics signal that the writer knows the subject. Abstractions signal that the writer might be guessing.

Prefer Active Voice

Active voice puts the actor before the action. Passive voice puts the action before the actor or hides the actor entirely.

Active: "The function validates the input before processing it."

Passive: "The input is validated before being processed."

Use active voice as the default. It is shorter, clearer, and more direct. Switch to passive voice only when the action matters more than the actor, or when the actor is unknown or irrelevant.

Justified passive: "The vulnerability was discovered in 2019." (Who discovered it is less important than when.)

Unjustified passive: "The configuration file is read by the application at startup." (The actor matters here. Write: "The application reads the configuration file at startup.")

One Idea per Paragraph

Each paragraph should make one point. If you find a paragraph making two distinct points, split it into two paragraphs. The topic sentence states the point. The remaining sentences support it. When the support is complete, start a new paragraph for the next point.

Long paragraphs are not inherently bad. A paragraph can be long if every sentence supports the same point. But a paragraph that wanders between multiple ideas confuses the reader about what the paragraph is actually arguing.

Test: Can you summarize the paragraph in one sentence? If you need two sentences, it is probably two paragraphs.

Transitions and Flow

Good transitions make the reader forget they are reading sections. The content simply flows from one idea to the next.

Logical connection over transition words. If the ideas connect logically, the transition is often implicit. Do not force transition words ("However," "Furthermore," "Additionally") where the logic already carries. Use them when the relationship between ideas is genuinely surprising or when the direction shifts.

End of section creates pull. The last sentence of a section should make the reader want to read the next section. It can do this by raising a question, identifying a consequence, or previewing what comes next. It should not do this by saying "In the next section, we will discuss..."

Paragraph-level flow. Within a section, each paragraph should follow naturally from the previous one. If you have to force a transition between paragraphs, the order might be wrong. Try rearranging before adding transition language.

Anti-Patterns

These are the most common sentence-level problems. Recognizing them is the first step to avoiding them.

Wall of text. Long, unbroken paragraphs with no visual breaks. Readers skip them. Split into shorter paragraphs. Use headings and lists when the content supports them.

Buried lede. The main point appears in the middle or end of the paragraph instead of the beginning. Restructure so the point comes first.

Abstract language. Vague terms that could mean anything. Replace with specific, concrete language. If you cannot make it concrete, you may not understand the subject well enough to write about it yet.

Passive voice overuse. Occasional passive voice is fine. Consistent passive voice makes prose feel evasive and bureaucratic. If more than one in four sentences uses passive voice, revise.

Monotonous sentence length. Every sentence the same length creates a drone. Vary deliberately. Follow a long sentence with a short one. Or vice versa.

Technical Writing Reference

This reference covers writing considerations specific to technical content, including term handling, example placement, information structure, code samples, and SEO.

Define Terms on First Use

When a technical term appears for the first time, define it immediately. After the definition, use the term consistently throughout the piece without redefining it.

First use: "The ORM (Object-Relational Mapper) translates between database rows and application objects."

Subsequent uses: "The ORM handles this conversion automatically."

Do not assume the reader knows the term. Do not define it multiple times. Do not switch between the term and a synonym. Consistency reduces cognitive load.

If a piece uses many technical terms, consider a glossary section. But the in-text definition on first use is still required even if a glossary exists.

Use Examples Immediately After Concepts

Abstract explanations followed by examples stick. Abstract explanations without examples fade. Place an example as close to the concept as possible.

Pattern: 1. State the concept in one or two sentences. 2. Show an example immediately. 3. Explain what the example demonstrates if it is not obvious.

Do not stack multiple concepts before showing examples. Each concept gets its own example before moving to the next concept.

Inverted Pyramid: Most Important Information First

Put the most critical information at the top. Follow with supporting detail. End with background and context.

This structure serves readers who scan (most of them) and readers who read deeply (they get the important part first, then the detail they want). It also makes content resilient to truncation. If a reader stops halfway through, they still got the most valuable information.

Apply the inverted pyramid at three levels:

• Article level: The most important takeaway appears in the introduction.
• Section level: Each section opens with its key point.
• Paragraph level: Each paragraph leads with its main claim.

Code Samples

Code samples in technical writing serve a specific purpose: they make abstract concepts concrete. They are not documentation. They are not production code. They are teaching tools.

Minimal. Include only the code that illustrates the concept. Strip out error handling, logging, configuration, and anything else that is not directly relevant. If the reader needs the full implementation, link to a repository.

Correct. Every code sample must work. A broken code sample destroys credibility faster than any prose mistake. If you cannot verify the code runs, say so explicitly.

Commented. Add brief comments that connect the code to the concept being explained. Do not comment every line. Comment the lines that matter.

# Connect using connection pooling to reuse database connections
pool = ConnectionPool(max_size=10)
conn = pool.acquire()  # Returns existing connection or creates new one

Language-appropriate. Match the code language to the audience. If the article is about a Python library, use Python. If the audience is polyglot, choose the language that makes the concept clearest.

SEO Writing Considerations

SEO and clear writing are not in conflict. Good SEO practice is largely good writing practice with a few structural additions.

Primary keyword in the first 100 words. Introduce the primary keyword naturally in the opening paragraph. Do not force it. If it does not fit naturally in the first 100 words, the introduction may need restructuring anyway.

Secondary keywords in H2 and H3 headings. Use secondary keywords in subheadings where they fit naturally. Headings serve readers first and search engines second. A heading that confuses the reader to include a keyword is a bad heading.

Headings as clear descriptive signposts. Every heading should tell the reader exactly what the section covers. Clever or vague headings hurt both readers and search rankings. "How Connection Pooling Reduces Latency" is better than "The Pool Problem" or "Going Deeper."

Short paragraphs. Keep paragraphs to 2-4 sentences for web content. Long paragraphs discourage reading on screens. This is good writing practice regardless of SEO.

Eighth-grade reading level. Write clearly enough that a general audience can follow. This does not mean dumbing down technical content. It means using direct sentences, common words where they suffice, and defining specialized terms when they are necessary.

Semantic keyword variations. Use natural variations of the primary keyword throughout the piece. If the primary keyword is "connection pooling," also use "pool connections," "database connection pool," and "pooled connections" where they fit naturally. Do not force variations. If they do not fit, the content does not need them.

Meta description candidate. Write one sentence of 150-160 characters that summarizes the article and includes the primary keyword. This sentence often works as the article's opening line or as a standalone summary for search result snippets.

Meta description: "Connection pooling reduces database latency by reusing
open connections instead of creating new ones for every query."
(142 characters)