> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Write better descriptions

> A Shape's descriptions tell agents what each concept means, and those meanings agree across the whole Shape.

Guide · shapes

> **Use when**
>
> Shape, type, property or relationship descriptions are vague, redundant, circular or conflicting. Agents confuse concepts, guess missing values or invent confidence percentages.

> **Looking for something else?**
>
> Rewording a File or an entity's content. Publishing and compatibility checks belong to recipe [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md).

## Outcome

Each description explains what an agent should recognize or put in a field.
The descriptions also agree about the Shape's purpose, boundaries and relationships.
Unknown information stays unknown, and uncertainty has a stated meaning.

## Before you start

1. Read the whole Shape with `penumbra shapes show <shape>`.
   State the question it helps a person answer.
2. Follow recipe [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md) to open an edit draft, or [create-a-shape](https://docs.pnbr.io/guides/create-a-shape.md) for a new Shape or a fork.
   Pull the draft with `penumbra shapes pull <draft-id>`.
3. Keep the generated [source](https://docs.pnbr.io/concepts/source.md) and every `*_ref`.
   Identify which descriptions need attention before changing the file.
   A request to improve wording does not authorize unrelated changes to types or required fields.

## Steps

1. Read every field that carries meaning, including examples and allowed values.
   Use this map to find the supported fields.

   | Place | What its text must make clear |
   | - | - |
   | Shape `description` and `telos` | The question, intended reader and useful outcome. |
   | Type `description` and `semantics` | What qualifies, what does not, and how examples fit the definition. |
   | Property `schema.description` | What a value means, its scope and units where relevant, and when it is absent. |
   | Enum property's `schema.description` | What each allowed value means and how a reader distinguishes adjacent values. |
   | Relationship `description` | What holds between its source and target, in that direction, and when the relationship is supported. |

2. Improve each description on its own.
   Define the concept rather than repeating its name.
   Replace vague praise or topic labels with the distinction an agent needs.
   Give each sentence a purpose; remove repetition that adds no meaning.

   | Weak description | Clearer description |
   | - | - |
   | “Priority is the priority of the issue.” | “The order in which the team intends to address the issue. It does not measure severity.” |
   | “Assessment date.” | “The date the assessment occurred. Omit it when unstated; the document's date alone does not establish it.” |
   | “Whether the data is good.” | “Whether the named dataset meets this requirement. Use `unknown` when its suitability has not been assessed.” |
   | “Requires relates an opportunity to a requirement.” | “The opportunity depends on this data condition. The relationship does not say the condition is satisfied.” |

3. Read the descriptions together.
   Use the same term for the same concept, and distinguish concepts that answer different questions.
   Check both endpoints of every relationship against its description.
   Make examples agree with the definition and allowed values.
   Remove conflicting instructions and duplicated fields whose different purposes cannot be explained.
   If removing a field would change the structure, propose that change through recipe [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md).

   Keep these distinctions where the Shape needs them:

   * A proposed action and an approved action.
   * A required condition and a condition already satisfied.
   * A source's claim and an observed result.
   * An event date and the date of the document describing it.
   * Missing information and an explicit negative finding.

4. Describe uncertainty with defined states before choosing numerical confidence.
   Prefer an enum whose values express what is known about the particular claim or judgment.
   Define every value in the property's description.
   Do not substitute undefined labels such as `high` and `low` for unexplained percentages.

   For a property describing source support for a claim, one possible definition is:

   ```json theme={null}
   {
     "type": "string",
     "enum": ["supported", "contradicted", "mixed", "unresolved"],
     "description": "How the reviewed source material bears on this claim within the stated scope. supported: it supports the claim without material contradiction. contradicted: it contradicts the claim without material support. mixed: material support and contradiction both remain. unresolved: the reviewed material establishes neither. These values describe source support, not approval, importance or certainty that the claim is true."
   }
   ```

   Choose states that fit the field; do not apply this example to every uncertainty.
   Approval, severity, readiness and source support answer different questions.
   Keep them separate when the Shape needs each distinction.
   An omitted property and an explicit `unresolved` value also need distinct meanings.

   Retain a number when it has a defined measurement or probability interpretation and a stated basis.
   Explain its units, range and origin.
   Do not ask an agent to invent precision through a confidence percentage.
   Replacing a numeric property with an enum changes its schema; review compatibility through recipe [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md).

5. Make the descriptions agree with the schema.
   An optional property can be absent when the source does not establish its value.
   For a required property, explain when the type should be absent instead of filled with a guess.
   If the person needs the entity despite that missing value, review whether the property should become optional.
   Do not hide that structural decision inside a wording edit.

6. Save the changes using `penumbra shapes push <name>.shape.json`.
   Run `penumbra shapes check <draft-id>` and `penumbra shapes diff <draft-id>`.
   Resolve relevant diagnostics and inspect the actual changed fields.
   Follow recipe [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md) for publication, permissions and effects on existing entities.

7. Try the published version on relevant Files using recipe [extract-files](https://docs.pnbr.io/guides/extract-files.md), within the person's authorized scope and cost.
   When comparing descriptions, keep the source versions and extraction level the same.
   Read the workspace before correcting its items.
   Check whether the concepts remain distinct and whether missing values stay absent or explicitly unknown, as intended.

## Check

* Each description explains a useful distinction without circular definitions, redundant sentences or contradictory examples.
* Types, properties, enum values and relationships agree with the Shape's purpose and with each other.
* Every uncertainty state answers one defined question; numerical precision has a stated basis.
* Schema checks pass, and the diff contains only intended changes.
* Describe observed extraction behavior separately from schema validity. A valid Shape does not prove that its descriptions work well on Files.

## If it goes wrong

| What you see | What to do |
| - | - |
| Two descriptions make the same concept look different | Align the terms, or state the distinction that makes both necessary. |
| A relationship says more than either endpoint supports | Narrow its meaning and check the source passages for that particular relationship. |
| The agent fills a missing date or makes a requirement sound completed | Clarify the relevant property and type descriptions, including absence and conditions. Try the changed version on the same Files. |
| Clear wording still produces unsupported findings | Keep the example and its citations. Do not call the wording effective or submit the findings without review. |
| A numeric property needs to become an enum | Follow recipe [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md); it is a schema change. |
| Push or publication fails | Follow the recovery instructions in [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md) or [create-a-shape](https://docs.pnbr.io/guides/create-a-shape.md). |

## Worth offering

* Keep a small set of Files and expected distinctions to try after later description changes.
* Compare a familiar example with a different example before claiming the descriptions work across projects.
* Use recipe [review-and-submit](https://docs.pnbr.io/guides/review-and-submit.md) for findings the person wants in the Graph.

## Report

Tell the person which descriptions changed and what ambiguity each change resolves.
Name any schema changes separately, including new enum values or changed requiredness.
State whether the draft was published, which Files and extraction level were tried, and what still needs review.

## Keep going

[Shape](https://docs.pnbr.io/concepts/shape.md) · [Shape draft](https://docs.pnbr.io/concepts/shape-draft.md) · [Create a Shape and try it on a File](https://docs.pnbr.io/guides/create-a-shape.md) · [Change a Shape and publish it](https://docs.pnbr.io/guides/change-a-shape.md) · [Extract entities from Files](https://docs.pnbr.io/guides/extract-files.md) · [Review a workspace and submit it](https://docs.pnbr.io/guides/review-and-submit.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.