armelhbobdad/oh-my-skills / .claude/skills/skf-refine-architecture
skf-refine-architecture
VerifiedRefines an architecture document against generated skills and a Verify Stack report. Use when the user requests to "refine the architecture against generated skills" or "refine an architecture doc with a VS report."
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.6 KB |
| customize.toml | config | 4.2 KB |
| references/compile.md | markdown | 17.6 KB |
| references/exit-codes.md | markdown | 5.6 KB |
| references/finding-storage.md | markdown | 3.3 KB |
| references/gap-analysis.md | markdown | 19.8 KB |
| references/health-check.md | markdown | 901 B |
| references/improvements.md | markdown | 5.3 KB |
| references/init.md | markdown | 18.2 KB |
| references/issue-detection.md | markdown | 8.1 KB |
| references/refinement-rules.md | markdown | 8.1 KB |
| references/report.md | markdown | 9.9 KB |
| scripts/skf-check-preservation.py | script | 74.2 KB |
references/report.md
View on GitHub---
outputFile: '{outputFolderPath}/refined-architecture-{arch_project_name}.md'
nextStepFile: 'health-check.md'
# The records scripts/skf-check-preservation.py wrote at step 1 and step 5.
inspectResult: '{run_dir}/inspect.json'
applyResult: '{run_dir}/apply.json'
promoteResult: '{run_dir}/promote.json'
preservationScript: 'scripts/skf-check-preservation.py'
emitEnvelopeProbeOrder:
- '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
- '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
---
<!-- Config: communicate in {communication_language}. Render the user-facing summary in {document_output_language}. -->
# Step 6: Present Report
## STEP GOAL:
Present where the refined document is, the skills its evidence came from and the next steps, write the result contract, run the post-completion hook and finish the run. Every count comes from the files the preservation script wrote. Chains to the shared health check.
## Rules
- Focus only on presenting the completed refinement: no new analysis
- Do not discover new gaps, issues, or improvements, and do not modify the refined document
- Take every count from `{applyResult}`, never from a `## Refinement Summary` in a document: an architecture document refined before can hold an older one
- Chains to the local health-check step via `{nextStepFile}` after completion: the user-facing summary is not the terminal step
## MANDATORY SEQUENCE
**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. In headless mode, stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "refined_path": "{outputFile}"}` (step 5 promoted it), resolve `{emitEnvelopeHelper}` from `{emitEnvelopeProbeOrder}` if it is not bound (first existing path wins), then run:
```bash
uv run {emitEnvelopeHelper} emit-halt --workflow skf-refine-architecture --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
```
Display the line it prints, then stop with the halt's exit code (`references/exit-codes.md` describes the envelope). If no candidate exists, or the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
### 1. Load the Run's Numbers
**Run recovery:** if `{run_dir}` or `{arch_project_name}` is no longer bound, read it from the `<!-- [RA-RUN] -->` block of `{forge_data_folder}/ra-state-{project_name}.md`.
Stage the result contract's payload from the records of step 1's check for an earlier pass, step 5's build of the draft and its promotion to `{outputFile}`:
```bash
uv run {preservationScript} context --inspect "{inspectResult}" --apply "{applyResult}" --promote "{promoteResult}" --out "{run_dir}/result-context.json"
```
- **0:** `{run_dir}/result-context.json` holds the payload §4 hands the emitter.
- **2** with a JSON: a record is missing or is not its step's (`error` names it): HALT (exit code 8, `halt_reason: "recovery-failed"`) at phase `report:numbers`: "⚠️ The record of the refined document's build or promotion is missing ({error}). Re-run [RA] from the beginning." **2 with no JSON:** fix the malformed call and run it again.
- **3:** HALT (exit code 4, `halt_reason: "write-failed"`) at phase `report:numbers`, naming its `error`.
- If `uv` cannot start the script: HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `report:numbers`.
**Bind what §2 and §3 show from the files:** the Evidence Sources from `evidence` of `{applyResult}`; `unverified_count` from `counts.unverified` and `unverified_technologies` from its `unverified_technologies` (comma-separated, or `none`), the list the count was taken from; `counts.issue_tiers`, which lists the severity tiers of the refinement rules, most severe first, with their counts; `{ranges}` from the `legacy` entries of `set_aside`, each as `start`-`end`; `previous_refined_path` from the `previous` of `{promoteResult}` (null when no earlier refined document was there); and `previous_pass` from `{inspectResult}`.
### 2. Display Summary
Show no count table: the step 5 review showed every count, and a headless run's result line (§4) carries `gap_count`, `issue_count`, `improvement_count` and `unverified_count`.
"**Refine Architecture: Refinement Complete**
---
**Evidence Sources:** (which skills contributed evidence)
{One row per entry of `evidence`: the skill and how many refinements cite it}
---
**Your refined architecture is at:** `{outputFile}`
{IF previous_refined_path:}Your earlier refined document was kept as `{previous_refined_path}`.
{IF previous_pass:}The earlier Refine Architecture pass in your document was set aside: these refinements replace it.
{IF `{ranges}` is empty:}The original architecture content is preserved in full: the preservation script found every line unchanged before step 5 promoted the draft.{ELSE:}Every original line is preserved except lines {ranges} of the document this run refined (kept as `{previous_refined_path}` when it was the refined document itself), which an earlier pass left without RA markers: they were set aside unchecked, so text of your own there is not in the refined document.{END IF} Every refinement sits between `<!-- RA:BEGIN ... -->` and `<!-- RA:END -->` marker lines, in `[!NOTE]`, `[!WARNING]` and `[!TIP]` callout blocks."
### 3. Present Next Steps
"**Recommended next steps:**
{IF unverified_count > 0:}
**Generate the missing skills first:** no skill covers {unverified_technologies}, so nothing checked what the architecture says about them. Create their skills with **[CS] Create Skill** or **[QS] Quick Skill**, then re-run **[RA]** before moving on to **[SS] Stack Skill**.
1. **Review the refined document:** to accept a refinement, move what you keep into your own prose, outside its `<!-- RA:BEGIN ... -->` and `<!-- RA:END -->` markers. Anything still between RA markers is replaced the next time you run [RA] on this document. A finding you dropped at the review stays out of later [RA] runs on this document, while a block you delete by hand, markers included, is gone from this copy only: a later [RA] run that finds the same thing again adds it back
2. **[SS] Stack Skill**: compose-mode activates automatically when SS detects existing individual skills without a codebase; provide this refined architecture doc as the architecture document when prompted
3. **Re-run [VS] Verify Stack** if you made changes based on issue corrections, to confirm resolution
{IF the first tier of `counts.issue_tiers`, the most severe, counts any issue:}
**⚠️ Attention:** {its count} {its tier} issue(s) were flagged. These indicate fundamental contradictions between your architecture and the verified API surfaces. Address these before proceeding to stack skill composition."
### 4. Result Contract
The shared emitter writes the result contract (per `shared/references/output-contract-schema.md`, which resolves relative to the SKF module root: `{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during development) and prints the envelope from the payload §1 staged, every count from `{applyResult}`. Run, in every mode:
```bash
uv run {emitEnvelopeHelper} emit --workflow skf-refine-architecture --run-dir "{run_dir}" --result-dir "{outputFolderPath}" < "{run_dir}/result-context.json"
```
It writes `{outputFolderPath}/refine-architecture-result-{YYYYMMDD-HHmmss}.json` and its `refine-architecture-result-latest.json` copy (a copy, not a symlink: the record of the last run whose emitter wrote this copy, at a stable path; a caller reads its own run's `SKF_REFINE_ARCHITECTURE_RESULT_JSON` line), stamping the time, the run id, the run's warnings and the auto-decisions the gates recorded, and prints the `SKF_REFINE_ARCHITECTURE_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, display the line verbatim. Bind `{result_path}` ← the line's `result_path`: a per-run record that could not be written leaves it null, and a `-latest` copy that could not be written leaves it set; either adds a `result_file_write_failed` warning to the line, and the run still finishes. If the emitter exits non-zero, run §1's `context` command and the emitter once more; if it fails again, HALT (exit code 4, `halt_reason: "write-failed"`) at phase `report:result-contract`: the run's result contract could not be written.
### 5. Post-Completion Hook (optional)
Skip this section when `{onCompleteCommand}` (resolved at SKILL.md On Activation §4 from `workflow.on_complete`) is empty, the bundled default. When `{result_path}` is null, skip it too, with one line saying no result file was written for the hook to read. Otherwise invoke it now, after the emitter wrote the per-run record, so a notifier, indexer or chained pipeline sees a complete record:
```bash
{onCompleteCommand} --result-path="{result_path}"
```
Run it with a bounded timeout. On success, continue. On a non-zero exit, a timeout or any other failure, display "**Warning:** on_complete failed: {reason}" (for example `exit {N}: {stderr_first_line}`) on its own line of this report, in headless too, and continue: the hook never fails the workflow, since the refined document and its result contract are already written. The warning is in neither the envelope nor the result file: the hook reads the result file, so both are written before it runs.
### 6. Finish the Run
The walkthrough of each refinement belongs to step 5's review, where feedback can still change the draft, so this step asks nothing. Display:
"**Refined architecture saved to:** `{outputFile}`
Re-run **[RA] Refine Architecture** anytime after updating your skills or architecture document: run on this refined document, it replaces the blocks between RA markers with a current set and keeps everything else.
**Architecture refinement complete.**"
Then delete the run folder, whose analysis copy, plan and payloads the run no longer needs: `rm -rf "{run_dir}"`. Then load, read the full file, and execute `{nextStepFile}`: the health-check step is the true terminal step of this workflow, so do not stop here even though the message above reads as final.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |