Skip to content

armelhbobdad/oh-my-skills / .claude/skills/skf-refine-architecture

skf-refine-architecture

Verified

Refines 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."

references/exit-codes.md

View on GitHub
# Exit Codes and Result Envelope

Every hard halt in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text. Each code pairs with a `halt_reason` string carried in the headless result envelope.

| Code | Meaning              | Raised by                                                                                    |
| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
| 0    | success              | step 7 (terminal)                                                                           |
| 2    | input-missing / input-invalid | step 1 §1 (headless with no `--architecture-doc`) → `input-missing`; step 1 §1 (an architecture document that is missing or unreadable, or a [VS] report that breaks the feasibility-report contract (`schemaVersion` not `1.0`, a section missing or out of order, a missing or second verdict table, an unknown verdict token) or cannot be read), step 1 §1b and step 5 §6 and §8 (the architecture document cannot be read as UTF-8 text) → `input-invalid` |
| 3    | resolution-failure   | On Activation §5 (`output_folder` or `forge_data_folder` unconfigured → `output-folder-unconfigured` / `forge-folder-unconfigured`; the result emitter is not installed → `resolution-failure`); a helper is not installed, cannot start or fails: step 1 §2 (`skf-enumerate-stack-skills.py`, phase `init:inventory`), step 2 §2 (`skf-comention-pairs.py`, phase `gap-analysis:comention`); a helper is not installed or `uv` cannot start it: step 1 §1 (`skf-validate-feasibility-report.py`, phase `init:feasibility-validator`), step 1 §1b, step 3 §4, step 5 §6 and §8 and step 6 §1 (`scripts/skf-check-preservation.py`, or at step 3 §4 the shared feasibility-report reader it runs) → `resolution-failure`; step 1 §4 (the refinement rules cannot be read, lack a table the steps read or name a tier the Refinement Summary cannot count) → `resolution-failure` |
| 4    | write-failure        | On Activation §5 (the write probe, the run folder); step 1 §1b (the analysis copy); step 1 §3c (the RA state file); step 5 §6 (the draft) and §8 (the promotion, or a draft that still cannot be read after one rebuild); step 6 §1 (the result payload) and §4 (the emitter refuses it twice) → `write-failed`; step 5 §6 (in headless, the draft would lose or change a line of the original) and §8 (it still would after one rebuild) → `preservation-failed` |
| 5    | state-conflict       | step 1 §3 (no skill SKF generated was found: refinement requires ≥1 skill) → `insufficient-skills` |
| 6    | user-cancelled       | step 1 §1 prompt cancelled; step 2 §2b scope confirmation `[X]`; any prompt that accepted `cancel`/`exit`/`:q`; step 5 review gate `[X]` (the draft is deleted, `{outputFile}` is unchanged) |
| 7    | inventory-unreliable | step 1 §2 (skill-inventory warnings exceed the failure budget); skills SKF did not generate are not counted |
| 8    | recovery-failed      | step 3 §4 (the [VS] report cannot be read again, or [VS] rewrote it during the run, or the refinement rules no longer pass step 1's check); step 5 §1 (the saved state is not enough to rebuild the Step 02-04 findings, the scope or the VS report); step 6 §1 (a record of the draft's build or promotion is missing) |

## Result Envelope

When `{headless_mode}` is true, step 6 prints one `SKF_REFINE_ARCHITECTURE_RESULT_JSON: {...}` line on **stdout** when it writes the result contract, and every HARD HALT prints one on **stderr** with `status: "error"`. The shared emitter builds each line from the payload the stage stages in `{run_dir}`, folds in the decisions and warnings the run recorded there, and checks it against `{project-root}/_bmad/skf/shared/scripts/schemas/skf-refine-architecture-result-envelope.v1.json` (`{project-root}/src/shared/scripts/schemas/skf-refine-architecture-result-envelope.v1.json` in a dev checkout), whose descriptions say what each field holds: `status`, `refined_path`, `previous_refined_path`, `previous_pass`, `gap_count`, `issue_count`, `improvement_count`, `unverified_count`, `exit_code`, `halt_reason`, `run_id`, `result_path`, and `headless_decisions`, `warnings` and `error` when they apply. Never type the line yourself.

`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"insufficient-skills"`, `"output-folder-unconfigured"`, `"forge-folder-unconfigured"`, `"resolution-failure"`, `"inventory-unreliable"`, `"write-failed"`, `"preservation-failed"`, `"recovery-failed"`, `"user-cancelled"`. `exit_code` matches the table above, and the emitter derives it from `halt_reason`.

## Emitting a Halt

Every HALT 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>"}`, adding `"refined_path": "{outputFile}"` once step 5 promoted the draft and `"path"` when the halt names one, then run:

```bash
uv run {emitEnvelopeHelper} emit-halt --workflow skf-refine-architecture --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
```

Each stage that halts shows this command and the probe order that resolves `{emitEnvelopeHelper}`, so a late halt emits the right line even when this file is not in context. Display the line it prints, then stop with the halt's exit code. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing. A HALT before the run folder exists (SKILL.md On Activation §5) passes the payload on stdin instead.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall