Skip to main content

Capability Guide Template

How should a capability guide move a learner from supported practice to independent transfer?

Capability guides turn human potential into trainable agency while keeping Purpose and beneficiary value visible.

Use this template for /playbook/agency/capabilities/** pages and any page whose job is to improve a capability a person or team can practice.

Instructions​

Page type: concept. Diataxis class: explanation with embedded playbook. Writing layer: Hemingway, always.

Primary reader: a human improving agency. Secondary reader: an AI agent classifying, routing, checking, or improving the page.

Rules:

  1. Open with one provocative sentence. No preamble.
  2. Put a visual immediately after the opener: YouTube iframe or generated image/component.
  3. If no excellent video exists and no generated visual exists, do not publish visual-free.
  4. Store reusable presentation shapes in the nearest _production/patterns/**; keep runtime code with its executable owner.
  5. Use bullets and short labelled blocks before tables.
  6. Use tables only for compact comparisons that work on mobile.
  7. Every heading is three words or fewer.
  8. Teach the capability through map, demonstration, guided practice, fading, independent action, transfer, beneficiary evidence, and reinvestment.
  9. Include ## Agent Use so AI agents know the page job, page type, and improvement target.
  10. End with ## Context and 3-6 links with scent.
  11. Do not leak private project state into reader-facing content.

Page Shape​

Use this order.

---
title: Capability Name
sidebar_label: Capability Name
description: "Direct answer to what this capability helps the reader do."
tags:
  - Capabilities
  - Agency
type: concept
loop_phase: action
level: working
---

Provocative opener.

<div className="iframe-container">
  <iframe
    className="responsive-iframe"
    src="https://www.youtube.com/embed/VIDEO_ID"
    frameBorder="0"
    height="400"
    allowFullScreen
    width="100%"
  ></iframe>
</div>

Core insight in one or two sentences.

## Map

Name what the capability enables, the beneficiary, and the protected human authority.

## Demonstration

Show the whole capability and its important judgment points.

## Guided Practice

Give the smallest scaffold needed for the next reachable action.

## Fading

Remove support and repeat under comparable conditions.

## Independent Action

Show what the learner can understand, verify, decide, and do without support.

## Transfer

Apply the capability in a materially different context.

## Beneficiary Evidence

Observe whether another person received useful value and what unintended effects occurred.

## Reinvestment

Use the evidence to `reinvest`, `adapt`, `redirect`, or `stop`.

## Shadow

Name the failure mode of overuse or misuse.

## Agent Use

Tell AI agents how to classify and improve the page.

## Questions

Ask questions that improve agency.

## Context

- [Related page](/playbook/) — why it matters

Content Rules​

Hemingway first. Cut throat-clearing. Use short sentences. Prefer strong verbs. Keep the core sentence visible.

Pattern before detail. The brain learns through repeated shapes. Name the loop before explaining parts.

Transfer before summary. A capability page fails if the reader cannot act independently, try a second context, and gather beneficiary evidence.

Mobile first. Use labelled bullets, short lists, and narrow comparisons. Avoid wide tables. If a table needs more than three columns, rewrite it.

AI readable. Use frontmatter, stable headings, direct definitions, and ## Agent Use. Agents should know the page job without inferring it from prose.

Agency focused. The page exists to develop agency without sacrificing judgment, vitality, belonging, integrity, or beneficiary value.

Visual Rule​

Every capability guide needs one first-screen visual.

Use one of these:

  • YouTube iframe — when a single excellent video explains the idea better than text.
  • Generated image or component — when the page teaches a loop, contrast, or system.
  • Future Module candidate — when the visual need repeats across pages and should become reusable.

The visual is not decoration. It must make the pattern easier to remember.

Agent Use​

  • Page type: concept
  • Template: capability-guide-template
  • Primary job: improve a trainable agency capability
  • Required media: YouTube iframe or generated visual
  • Writing layer: Hemingway
  • Mobile rule: avoid wide tables
  • AI target: frontmatter, stable headings, and direct practice protocol

Failure Modes​

  • Publishing a static scaffold that never fades.
  • Claiming learning from assisted output without independent transfer.
  • Requiring a visual that decorates rather than improves judgment.
  • Letting a template override evidence, consent, or the learner’s actual state.

Changes my mind: evidence that another page shape more reliably produces independent transfer and beneficiary value should revise this template.

Context​

Questions​

  • What is the one capability this guide develops?
  • What does the learner do unaided before and after support?
  • Which second context proves transfer?
  • What evidence shows a beneficiary received value?

Next question: Which scaffold should fade first?