Merge pull request #84 from managedcode/reviews-and-fixes

Reviews and fixes

Author: KSemenenko

.codex/skills/mcaf-adr-writing/SKILL.md

@@ -65,17 +65,20 @@ compatibility: "Requires repository write access; produces Markdown ADRs with Me
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 

.codex/skills/mcaf-agile-delivery/SKILL.md

@@ -62,17 +62,20 @@ compatibility: "Requires repository access only when the repo stores delivery do
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 

.codex/skills/mcaf-architecture-overview/SKILL.md

@@ -63,17 +63,20 @@ compatibility: "Requires repository write access; produces Markdown docs with Me
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 

.codex/skills/mcaf-ci-cd/SKILL.md

@@ -72,17 +72,20 @@ compatibility: "Requires repository access; may update CI workflows, pipeline do
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 
@@ -98,7 +101,7 @@ For setup-only requests with no execution, return `status: configured` and exact
 ## Load References
 
 - read `references/ci-cd.md` first
-- for .NET quality gates, use `mcaf-dotnet-quality-ci`
+- for .NET quality gates, use the external `mcaf-dotnet-quality-ci` skill from [managedcode/dotnet-skills](https://github.com/managedcode/dotnet-skills)
 
 ## Example Requests
 

.codex/skills/mcaf-code-review/SKILL.md

@@ -64,17 +64,20 @@ compatibility: "Requires repository access; may update PR templates, review docs
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 

.codex/skills/mcaf-devex/SKILL.md

@@ -63,17 +63,20 @@ compatibility: "Requires repository access; may update docs, task runners, devco
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 

.codex/skills/mcaf-documentation/SKILL.md

@@ -59,17 +59,20 @@ compatibility: "Requires repository write access; updates docs and documentation
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 

.codex/skills/mcaf-feature-spec/SKILL.md

@@ -65,17 +65,20 @@ compatibility: "Requires repository write access; produces Markdown docs with Me
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 

.codex/skills/mcaf-human-review-planning/SKILL.md

@@ -84,17 +84,20 @@ compatibility: "Requires repository read access; may write a `HUMAN_REVIEW_PLAN.
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format
 

.codex/skills/mcaf-ml-ai-delivery/SKILL.md

@@ -58,17 +58,20 @@ compatibility: "Requires repository access when ML/AI docs, experiments, or deli
 
 Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
 
-1. Plan first (mandatory):
+1. Brainstorm first (mandatory):
    - analyze current state
-   - define target outcome, constraints, and risks
-   - write a detailed execution plan
+   - define the problem, target outcome, constraints, and risks
+   - generate options and think through trade-offs before committing
+   - capture the recommended direction and open questions
+2. Plan second (mandatory):
+   - write a detailed execution plan from the chosen direction
    - list final validation skills to run at the end, with order and reason
-2. Execute one planned step and produce a concrete delta.
-3. Review the result and capture findings with actionable next fixes.
-4. Apply fixes in small batches and rerun the relevant checks or review steps.
-5. Update the plan after each iteration.
-6. Repeat until outcomes are acceptable or only explicit exceptions remain.
-7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+3. Execute one planned step and produce a concrete delta.
+4. Review the result and capture findings with actionable next fixes.
+5. Apply fixes in small batches and rerun the relevant checks or review steps.
+6. Update the plan after each iteration.
+7. Repeat until outcomes are acceptable or only explicit exceptions remain.
+8. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
 
 ### Required Result Format