decisions-and-findings

Files (1)

• SKILL.md

SKILL.md (first lines)

# Decisions and findings

Use this skill for each message that asks for a decision, presents review
findings, or gives a final report. The reader may have no context. The
reader must act on each item. A fixed layout lets the reader find each
field and answer by number and letter.

## Precedence

These rules are specific rules. They apply also when an output style or a
system prompt asks for brevity or plain prose. The layout is real
structure, not decoration. Brevity means fewer words. It does not mean
fewer fields or longer sentences.

A skill or a prompt for one task can set its own message order. Then use
that order, but keep the layouts, the labels, and the item order of this
skill.

## The decision test

Apply this test to each question before you write it as a decision. Look
at the option that you recommend. The question is a decision for the
user only when one of these conditions holds:

1. The recommended option changes a requirement or a decision in force.
2. The recommended option adds behaviour at a boundary that no
   requirement covers.
3. The recommended option is blocked under the review-fix rule in the
   `implementation-review` skill. It is Large, deletes functionality,
   adds a gate or stricter validation, weakens a test, or needs
   credentials or infrastructure.
4. Two or more options have real trade-offs, and no option is clearly
   best.
5. The user asked you to bring this choice to them.

A detail that an existing requirement settles is not a gap, also when the
requirement does not spell the detail out. An option that drops the
requirement does not make the question a decision when you do not
recommend that option.

When no condition holds, the question is a design call. Apply the
recommended option. Record the call, its reason, and the date in the
plan, in the design of the change. When the change has no plan, record
it in the commit or the pull request description. Do not ask the user.
Give each design call one line in the final report.

Three signs that a question fails the test:

- The recommendation says that the option costs nothing.
- The severity is Low, and the impact is only that the work waits for the
  answer.
- The **Auto-fix** reason says only that the item is a decision.

## Simplified Technical English

Write in Simplified Technical English (ASD-STE100):

- Use a maximum of 20 words in an instruction.
- Use a maximum of 25 words in a description.
- Write one instruction or one fact in each sentence.
- Use the active voice.
- Use a maximum of six sentences in a paragraph.
- Do not use semicolons. Do not put a clause or a list in parentheses.
- Use a vertical list for steps, options, and complex lists.
- Use one word for one thing. Define each project term once, then use it
  the same way.
- To give more detail, add sentences or list items. Do not make a sentence
  longer.

## Message order

1. Start with one or two sentences that give the result or the question.
2. When the items share background, add a background paragraph. Say what
   the project is, what the feature does, and what changed. Use six
   sentences or fewer. The **Background** of each item then adds only what
   that item needs.
3. When two or more items use the same term, add a shared **Terms** list
   after the background paragraph. The **Terms** of each item then adds
   only the terms that no other item uses.
4. With more than five items, add a summary table. Give the number, the
   title, the severity, the effort, and the recommended option. Use the
   same order as the items.
5. Give each item in the layout below.
6. When the task ends, finish with the final report.

## Item order

Keep the decisions and the review findings in two separate lists, each
under its own heading. In each list, order the items by severity: High
first, then Medium, then Low. Keep the relative order of items with the
same severity. Put the review findings first and the decisions second.
Number the items once across the whole message, in that order. The summary
table and the final report keep the same lists and the same order.

## Decision layout

Use this layout for each question that passes the decision test and is
not a review finding.

```markdown
### 1. <The problem, in eight words or fewer>

- **Severity:** <High, Medium, or Low>. **Effort:** <Small, Medium, or Large: the grade of the recommended option.>
- **Terms:** <Only when the item uses a term that the shared list does not define. Up to five entries.>
  - **<Term>:** <One sentence: what it is, and where it lives when that helps the reader find it.>
- **Background:** <Two to five sentences: what the feature does and where it is. Use plain words and defined terms only.>
- **Problem:** <One to three sentences that say what is wrong. Use plain words and defined terms only.>
- **Impact if no action:** <One or two sentences.>
- **Options:**
  - **A.** <The change.> <Its cost or risk.> Effort: <Small, Medium, or Large>.
  - **B.** <The change.> <Its cost or risk.> Effort: <Small, Medium, or Large>.
  - <More options as C, D, and so on, when the problem has them.>
- **Recommendation:** <Letter>. <One sentence of reasoning.>
- **Auto-fix:** no, because <the number of the condition of the decision test that holds, and one sentence of evidence.>
```

## Finding layout

Use this layout for each review finding, also when it needs a decision. A

From futex-ai/skills, MIT.

More from futex-ai/skills