Write better descriptions

​

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 to open an edit draft, or create-a-shape for a new Shape or a fork. Pull the draft with penumbra shapes pull <draft-id>.
3. Keep the generated source 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. 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:
   {
     "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.
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 for publication, permissions and effects on existing entities.
7. Try the published version on relevant Files using recipe extract-files, 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

​

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 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 · Shape draft · Create a Shape and try it on a File · Change a Shape and publish it · Extract entities from Files · Review a workspace and submit it