Browse Source

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

softword 2 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.
 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
-[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
 
 * Load skill `coding-standard-rules`.
@@ -82,9 +84,9 @@ Never renumber an ID after presenting it.
 
 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:
 
@@ -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.
 
-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.
 
@@ -113,12 +115,14 @@ Spawn one agent per microdevelopment. Parallelize only microdevelopments with no
 
 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.
 
@@ -130,9 +134,11 @@ The reviewer must inspect the diff, verify causal scope, acceptance criteria, in
 
 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:
 
@@ -140,6 +146,12 @@ Verdicts:
 * `CHANGES_REQUIRED`: fixable `REQUIRED` remain;
 * `REJECTED`: criteria cannot be met within scope or fixes are exhausted.
 
+Show the verdict as an H3 heading:
+
+```markdown
+### `CHANGES_REQUIRED`
+```
+
 ## 8. Fix
 
 For open `REQUIRED` findings:
@@ -170,46 +182,48 @@ When new files, behaviors, or decisions become necessary:
 
 # 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
 
-```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
 
-```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