--- name: refine-quality-profile description: Stage 2 skill of /arch. Reads the /specify quality profile, refines targets against architectural reality (inventory constraints, project-profile pins, epic constraints), and writes the refined quality profile to architecture/ with a delta log of every adjustment. The refined QP describes the NFRs physical must deliver; it does NOT name mechanisms. version: 0.1.0 user-invocable: false --- # refine-quality-profile > **Decision Surfacing Discipline:** This skill emits a `decision-manifest-refine-quality-profile.yaml` alongside its primary artifact. Every refinement to a /specify QP target is recorded as a decision with tier, grounding source, recommendation, and alternatives. The orchestrator drives the tiered surfacing flow after this skill completes. Called by `tech-designer` during `arch` Stage 2. Produces `quality-profile.yaml` at `{product_base}architecture/quality-profile.yaml` plus a decision manifest. ## Purpose The /specify play authored a first-cut quality profile from product intent. /arch refines it against the architectural reality surfaced during Stages 1-2 — the systems chosen in inventory carry their own scale, reliability, and security ceilings; project-profile pins may set hard floors; epic constraints may demand stricter targets than the first-cut allowed for. This skill is the bridge. The refined QP **describes** the NFRs the product must deliver. It does NOT name delivery mechanisms — those belong in physical-architecture. Same NFR, two views: this artifact is the target, physical is the mechanism. Outputs always carry a `delta_log[]` recording every adjustment (field, before, after, rationale citing the architectural driver). Security characteristics ratchet UP only — any security-related adjustment where `after < before` is a structural violation. Adjustments without a cited architectural driver are blocking. ## Input Receive from the `tech-designer` agent. All paths resolve against `{product_base}` and `{ltm_base}` supplied by the play via JSON contract. - `specify_qp_path` (path, required) — `{product_base}specification/quality-profile.yaml`. When missing or DRAFT under C1 soft pre-flight, the play writes `{product_base}specification/quality-profile-stand-in.yaml` from user answers; this skill reads that instead. - `scope_path` (path, required) — `{product_base}scope/scope.yaml`. - `epics_dir` (path, required) — `{product_base}scope/epics/`. Per-epic constraints may force a stricter target than the /specify QP allowed for. - `inventory_dir` (path, required) — `{product_base}architecture/systems-inventory/`. Each system file's Scale Profile and Tradeoffs sections may cap or force NFR targets. - `project_profile_path` (path, required) — `{product_base}user-provided/project-profile.yaml`. `grounded_tools.nfr_floors[]` and security/compliance pins are authoritative. - `kb_quality_dir` (path, required) — `{ltm_base}components/memory/knowledge/quality/`. ISO 25010 characteristic definitions and standard targets. - `output_path` (string, required) — `{product_base}architecture/quality-profile.yaml`. - `decision_manifest_path` (string, required) — `{product_base}architecture/decision-manifest-refine-quality-profile.yaml`. ## Output ### Refined quality profile YAML at `{output_path}` mirroring the /specify QP structure (every ISO 25010 characteristic with relevance, target, rationale) PLUS top-level `refined_from` and `delta_log[]` blocks. ```yaml refined_from: source_path: {product_base}specification/quality-profile.yaml source_sha: {sha256 at read time} refined_at: {ISO 8601 timestamp} # ISO 25010 characteristics — same structure as /specify QP. characteristics: functional_suitability: relevance: high | medium | low | not_applicable target: {prose target or quantified threshold} rationale: {why this level for this product} performance_efficiency: relevance: ... target: ... rationale: ... compatibility: ... interaction_capability: ... reliability: relevance: ... target: ... # e.g. "99.9% monthly uptime; RTO 4h; RPO 15min" rationale: ... security: relevance: ... target: ... rationale: ... maintainability: ... flexibility: ... safety: ... # Delta log — one entry per refinement made versus the /specify QP. delta_log: - id: D-001 characteristic: reliability # ISO 25010 characteristic field: target # which field changed before: "99.99% monthly uptime" after: "99.9% monthly uptime" direction: tightened | loosened | clarified driver: # MUST cite one architectural reality kind: inventory_constraint | project_profile_pin | epic_constraint | regulatory_pin reference: {inventory file path | profile slot | epic id | regulation cite} rationale: | {2-4 lines of prose explaining why the adjustment was made} ``` **Security ratchet rule.** For every delta where `characteristic = security`, `direction` MUST be `tightened` or `clarified`. A `loosened` security delta is a structural violation and halts the skill with `what_failed: security_ratchet_violation`. ### Decision manifest One YAML file at `{decision_manifest_path}` with one entry per delta_log entry. ```yaml manifest: skill: refine-quality-profile written_at: {ISO 8601 timestamp} decisions: - decision_id: RQP-001 decision_type: target_refinement tier: high | mid | low grounding_source: kind: inventory_constraint | project_profile_pin | epic_constraint | regulatory_pin | agent_default_with_user_approval citation: {path or slot or cite} recommendation: {summarized adjustment, e.g. "tighten reliability target to 99.9% per Salesforce SLA"} alternatives_considered: - option: {alt target} why_rejected: {one line} agent_reasoning_summary: | {2-4 line prose} user_response: accept | override | orbit | pending user_response_detail: {free text — null when pending} ``` ## Process ### 1. Read inputs - Parse `specify_qp_path` (or stand-in). Capture its full structure as the baseline. Compute `source_sha`. - Glob `epics_dir/*.yaml` → collect every per-epic constraint that names a quality dimension (performance budget, reliability, security level, compliance flag). - Glob `inventory_dir/*.md` → collect every system's Scale Profile + Tradeoffs sections. - Parse `project_profile_path` → `grounded_tools.nfr_floors[]`, security level pins, compliance flags. - Read `kb_quality_dir` index for ISO 25010 characteristic definitions when reasoning about relevance. ### 2. Validate pre-conditions - Required inputs exist OR documented stand-in exists. - Output path's parent directory exists. Missing required input with no stand-in → structured failure with `what_failed: missing_input`. ### 3. Establish the refined baseline Copy every characteristic block from the /specify QP into the refined QP's `characteristics:` section verbatim. Set top-level `refined_from.source_path` and `refined_from.source_sha`. The refined QP starts as a byte-for-byte copy of the input — every divergence MUST be recorded as a delta_log entry. ### 4. Walk each characteristic against architectural reality For each ISO 25010 characteristic, run these checks in order: 1. **Project-profile pin check.** If `project_profile.grounded_tools.nfr_floors[]` carries a pin for this characteristic, the pin sets a floor. If the /specify target is below the pin, force a tightening delta. If equal or above, no delta needed. 2. **Inventory constraint check.** For every system in inventory whose Scale Profile or Tradeoffs section names a hard ceiling that conflicts with the /specify target, propose a delta. Examples: - A chosen SaaS identity provider's published SLA caps reliability at 99.9% when /specify asked for 99.99% → propose `tightened: false, loosened: true` to align with the achievable ceiling, OR escalate (the choice of system may need to change). - A chosen analytics platform's data residency limitations contradict a compliance flag → propose tightening security/compliance or escalate. 3. **Epic constraint check.** For every epic whose constraints name a quality dimension stricter than the /specify QP target, propose a `tightened` delta with the epic ID as the driver. 4. **Regulatory pin check.** When `project_profile.compliance[]` lists regulations (HIPAA, PCI-DSS, SOC 2, GDPR) and the /specify target is below the regulatory floor for the relevant characteristic, force a `tightened` delta with the regulation as the driver. A delta is proposed whenever any of these checks fires. Multiple checks may converge on the same characteristic — record each as a separate delta_log entry so traceability is preserved. ### 5. Apply each delta and write the log For each proposed delta: - Verify the security-ratchet rule (Step 4 may have surfaced a loosening proposal for security characteristic — that halts with `what_failed: security_ratchet_violation`). - Update `characteristics.{characteristic}.target` and/or other fields per the delta. - Append a delta_log entry with id, characteristic, field, before, after, direction, driver, rationale. - Record a decision-manifest entry for the delta with tier resolution: - `tier: high` when grounding is a project-profile pin or regulatory pin (deterministic). - `tier: mid` when grounding is an inventory constraint with a published SLA / scale figure (sourced but agent-reasoned). - `tier: low` when grounding is agent reasoning over inventory Tradeoffs prose with no quantified source. ### 6. Loosening escalations When a proposed delta is `loosened` (e.g., a system ceiling forces a relaxation of the /specify target): - For non-security characteristics: surface at Stage 2 checkpoint per C19 tier. Loosening is a real adjustment but may be acceptable; the user decides. - For security characteristics: halt with `what_failed: security_ratchet_violation`. The orchestrator surfaces the conflict — either the system choice changes (orbit to Stage 1) or the /specify target was wrong. ### 7. Write outputs Write `{output_path}` with the full refined QP — every characteristic plus the delta_log. Write `{decision_manifest_path}` with one entry per delta. All `user_response` start as `pending`. ### 8. Validate output - Every characteristic in the /specify QP appears in the refined QP with at least its `relevance` carried forward. - Every delta_log entry has id, characteristic, field, before, after, direction, driver (with kind AND reference), and rationale (non-empty). - No security delta has direction `loosened`. - Refined QP names NO delivery mechanisms (regex check: rejects any phrase matching `delivered by`, `via {tool}`, `using {product}`, etc. — those are physical's concern). - Decision manifest has one entry per delta. Any failure → structured failure with `what_failed` and the offending block. ## Output Contract On success: ```json { "status": "success", "skill": "refine-quality-profile", "outputs": { "refined_qp_path": "{product_base}architecture/quality-profile.yaml", "decision_manifest_path": "{product_base}architecture/decision-manifest-refine-quality-profile.yaml", "delta_count": , "tightenings": , "loosenings": , "clarifications": , "halted_slots": [ { "characteristic": "...", "reason": "loosening_pending_user_decision | security_ratchet_violation" } ] } } ``` On failure: ```json { "status": "failure", "skill": "refine-quality-profile", "what_failed": "missing_input | security_ratchet_violation | delivery_mechanism_named | delta_without_driver | manifest_incomplete", "details": "..." } ``` ## Evals | Eval | Failure Bound | Check | |------|---------------|-------| | RQ-1 | F8 (NFR with no delivery mechanism — upstream check) | Every characteristic with `relevance != not_applicable` in the /specify QP appears in the refined QP. | | RQ-2 | F12 (QP delta uncited) | Every entry in `delta_log[]` has field, before, after, direction, driver.kind, driver.reference, and rationale, all non-empty. | | RQ-3 | C6 — security ratchet | No delta_log entry has `characteristic: security` AND `direction: loosened`. | | RQ-4 | Skill purity | Refined QP body contains no text matching `delivered by`, `via {tool}`, or named product/runtime tokens (delivery mechanism leakage). | | RQ-5 | F16 (manifest missing/malformed) | Decision manifest exists with one entry per delta; every entry has decision_id, decision_type, tier, grounding_source, recommendation, alternatives_considered. | | RQ-6 | C16 (KB read-only) | The skill wrote NO file under `kb_quality_dir`. | | RQ-7 | F13 (source_type discipline) | No decision has `grounding_source.kind: agent_default_unilateral`. | ## Constraints - Writes ONLY to `{output_path}` and `{decision_manifest_path}`. Read-only on every input. - NEVER names a delivery mechanism in the refined QP — physical owns that. - Security characteristics ratchet UP only. Loosening security is a structural violation. - Every delta cites an architectural driver (inventory constraint, project-profile pin, epic constraint, or regulatory pin). Agent reasoning alone is not a driver; it must reference one of the four kinds. - The skill NEVER modifies the /specify QP at `{product_base}specification/quality-profile.yaml` — that file is the authored intake and stays unmodified. ## Failure modes - `missing_input` — a required input path is absent and no stand-in exists. - `security_ratchet_violation` — a delta with `characteristic: security` has `direction: loosened`. - `delivery_mechanism_named` — the refined QP body contains text naming a delivery mechanism. - `delta_without_driver` — a delta_log entry has no `driver.kind` or no `driver.reference`. - `manifest_incomplete` — the decision manifest is missing or any entry lacks required fields.