Browse Source

docs(SKILL.md): enhance formatting and clarity of task tracking and planning sections

softword 3 days ago
parent
commit
e28d107e6c
1 changed files with 55 additions and 41 deletions
  1. 55 41
      skills/brainstorming/SKILL.md

+ 55 - 41
skills/brainstorming/SKILL.md

@@ -16,11 +16,13 @@ You must not create, modify, or delete any file directly.
 Follow these phases in order.
 Follow these phases in order.
 You **must** use `todos` tool to track progress and avoid skipping steps, else you can't work. If you don't have `todos`, simulate it with this output:
 You **must** use `todos` tool to track progress and avoid skipping steps, else you can't work. If you don't have `todos`, simulate it with this output:
 ```markdown
 ```markdown
-[X] todo 1
-[ ] todo 2
-etc
+`[X]` *todo 1*  
+`[ ]` **todo 2**  
+`[ ]` todo 3
 ```
 ```
 
 
+Done items in italic, the next pending item in bold, later items plain.
+
 ## 1. Brainstorm
 ## 1. Brainstorm
 
 
 * Load skill `coding-standard-rules`.
 * Load skill `coding-standard-rules`.
@@ -82,9 +84,9 @@ Never renumber an ID after presenting it.
 
 
 Show:
 Show:
 
 
-| ID     | Behavior         | Decision made     | Confirmed? |
-| ------ | ---------------- | ----------------- | ---------- |
-| MS-001 | Concise behavior | Relevant decision | Pending    |
+| ID         | Behavior         | Decision made     | Confirmed? |
+| ---------- | ---------------- | ----------------- | ---------- |
+| **MS-001** | Concise behavior | Relevant decision | *Pending*  |
 
 
 Then show the file map:
 Then show the file map:
 
 
@@ -95,7 +97,7 @@ path/to/file.ext (1 change)
 
 
 Every change must map to exactly one ID. Omit the map when no files change.
 Every change must map to exactly one ID. Omit the map when no files change.
 
 
-Ask exactly one approval question.
+Ask exactly one approval question, in bold italic: `***Approval question?***`.
 
 
 Approval must be explicit and case-insensitive, such as positive or negative words in the language of user.
 Approval must be explicit and case-insensitive, such as positive or negative words in the language of user.
 
 
@@ -113,12 +115,14 @@ Spawn one agent per microdevelopment. Parallelize only microdevelopments with no
 
 
 Require:
 Require:
 
 
-* implemented IDs;
-* changed files;
-* summary;
-* checks and results;
-* deviations;
-* blockers.
+```markdown
+**Implemented IDs:** `MS-001`  
+**Changed files:** `path/to/file.ext`  
+**Summary:** ...  
+**Checks and results:** ...  
+**Deviations:** ...  
+**Blockers:** ...
+```
 
 
 Do not apply changes yourself. Deviations require new authorization.
 Do not apply changes yourself. Deviations require new authorization.
 
 
@@ -130,9 +134,11 @@ The reviewer must inspect the diff, verify causal scope, acceptance criteria, in
 
 
 Classify findings as:
 Classify findings as:
 
 
-* `REQUIRED`: blocking fix;
-* `CONCERN`: non-blocking limitation;
-* `PASS`: satisfied criterion.
+```markdown
+***`REQUIRED`***: blocking fix  
+**`CONCERN`**: non-blocking limitation  
+`PASS`: satisfied criterion
+```
 
 
 Verdicts:
 Verdicts:
 
 
@@ -140,6 +146,12 @@ Verdicts:
 * `CHANGES_REQUIRED`: fixable `REQUIRED` remain;
 * `CHANGES_REQUIRED`: fixable `REQUIRED` remain;
 * `REJECTED`: criteria cannot be met within scope or fixes are exhausted.
 * `REJECTED`: criteria cannot be met within scope or fixes are exhausted.
 
 
+Show the verdict as an H3 heading:
+
+```markdown
+### `CHANGES_REQUIRED`
+```
+
 ## 8. Fix
 ## 8. Fix
 
 
 For open `REQUIRED` findings:
 For open `REQUIRED` findings:
@@ -170,46 +182,48 @@ When new files, behaviors, or decisions become necessary:
 
 
 # Output
 # Output
 
 
+Emit every template as rendered Markdown, never inside a code fence. Only the ASCII file map stays in a `text` fence. End a line with two trailing spaces when the next line of the same section must start on a new line.
+
 ## Planning
 ## Planning
 
 
-```text
-[OBJECTIVE]
-One-line outcome.
+```markdown
+**[OBJECTIVE]**  
+*One-line outcome.*
 
 
-[QUESTIONS]
-Maximum three.
+**[QUESTIONS]**  
+*Maximum three.*
 
 
-[OPTIONS]
-2–3 concise choices.
+**[OPTIONS]**  
+*2–3 concise choices.*
 
 
-[MICRODEVELOPMENTS]
-[MS-001] behavior, input, output, criterion, authorized file, call path, dependencies.
+**[MICRODEVELOPMENTS]**  
+`[MS-001]` behavior, input, output, criterion, `authorized file`, call path, dependencies.
 
 
-[PLAN]
-Ordered IDs, invariants, non-goals, checks.
+**[PLAN]**  
+*Ordered IDs, invariants, non-goals, checks.*
 
 
-[APPROVAL]
-Table, ASCII map, and one approval question.
+**[APPROVAL]**  
+*Table, ASCII map, and one approval question.*
 ```
 ```
 
 
 ## Final
 ## Final
 
 
-```text
-[RESULT]
-Status: COMPLETED | BLOCKED | REJECTED
-Fix rounds used: N / 3
+```markdown
+**[RESULT]**  
+Status: ***COMPLETED*** | ***BLOCKED*** | ***REJECTED***  
+Fix rounds used: **N / 3**
 
 
-[WHAT CHANGED]
-- [MS-001] observable result
+**[WHAT CHANGED]**
+- `[MS-001]` *observable result*
 
 
-[FILES]
-- changed file
+**[FILES]**
+- `changed file`
 
 
-[VALIDATION]
-- criterion or command: PASS | FAIL | NOT RUN
+**[VALIDATION]**
+- `criterion or command`: **PASS** | ***FAIL*** | ~~NOT RUN~~
 
 
-[KNOWN LIMITATIONS]
-- remaining CONCERN findings or None
+**[KNOWN LIMITATIONS]**
+- *remaining CONCERN findings or None*
 ```
 ```
 
 
 # Boundaries
 # Boundaries