derive-quality-vision

name	derive-quality-vision
description	Read quality-profile, nfr-spec, logical architecture, and physical architecture to produce quality-vision.yaml — a vision statement plus per-ISO-25010-characteristic entries carrying vision narrative, target level, design linkage, concrete named tooling, quantified thresholds, and lifecycle gates. Merges and extends the prior quality-standards artifact.
version	0.1.0
user-invocable	false
deprecated	true
deprecated_note	#434 ProductOS realignment — superseded by the command model; retained for Phase E reference, not installed

derive-quality-vision

DEPRECATED for /arch (#403). This skill is no longer part of the /arch pipeline. quality-vision is no longer a separate artifact — its work is folded into the refined quality-profile produced by refine-quality-profile. The refined QP carries every relevant ISO 25010 characteristic; delivery mechanisms live in physical-architecture's nfr_delivery[] blocks. This file is retained because /codify still references the quality-vision artifact shape through infer-quality-vision-from-code; aligning /codify with the new /arch contract is a separate follow-on. Do NOT invoke this skill in new /arch runs.

Defect 23 — Decision Surfacing Discipline (DSD): This skill emits a decision-manifest-derive-quality-vision.yaml alongside its primary artifact. Every inferred decision produced during execution is recorded in the manifest 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 4. Produces quality-vision.yaml at {product_base}architecture/quality-vision.yaml.

Purpose

Quality vision is the merged successor to the prior quality-standards.yaml. It adds the "why we care" narrative (the vision) to the existing "how CI will catch it" enforcement section. The output answers two questions per ISO 25010 characteristic: (1) What does quality mean for this product in this characteristic? (2) Exactly how does the architecture, the tooling, and the CI pipeline deliver and enforce it? Vague language ("use a linter", "test thoroughly") is a blocking failure (F8).

Input

Receive from the tech-designer agent. All paths resolve against {product_base} supplied by the play via JSON contract.

• quality_profile_path (path, required) — {product_base}specification/quality-profile.yaml
• nfr_spec_path (path, required) — {product_base}architecture/nfr-spec.yaml (NFR entries carry delivery mechanisms and verification methods that feed into design_linkage and tooling)
• logical_architecture_path (path, required) — {product_base}architecture/logical-architecture.yaml (component IDs for design_linkage)
• physical_architecture_path (path, required) — {product_base}architecture/physical-architecture.yaml (stack picks for tooling selection)
• project_profile_path (path, required) — {product_base}user-provided/project-profile.yaml (QP dimensions: QP-1 through QP-11 + team profile)
• ltm_quality_path (path, required) — {ltm_base}knowledge/quality/ (per-QP-dimension standard sets at each level)
• output_path (string, required) — {product_base}architecture/quality-vision.yaml
• decision_manifest_path (path, required) — {product_base}architecture/decision-manifest-derive-quality-vision.yaml

Process

1. Read inputs

• Parse quality-profile.yaml → each ISO 25010 characteristic with relevance, target, and rationale. Build a list of characteristics with relevance != not_applicable — these all require entries in the output.
• Parse nfr-spec.yaml → NFR entries grouped by characteristic. These are the concrete delivery mechanisms and verification methods already decided — use them as the primary source for design_linkage and tooling fields.
• Parse logical-architecture.yaml → component IDs and responsibilities (for design_linkage component references).
• Parse physical-architecture.yaml → stack picks (frontend, backend, data stores, observability, auth_infra, library_pins) — tooling is derived from these.
• Parse project-profile.yaml → QP dimensions (QP-1 Testing Depth, QP-2 Code Review, QP-3 Documentation, QP-4 CI/CD, QP-5 Observability, QP-6 Accessibility, QP-7 Security Testing, QP-8 Performance Testing, QP-9 Privacy, QP-10 Data Quality, QP-11 Tech Debt Governance) for selecting tooling level.
• Read {ltm_quality_path}/_index.md and the relevant per-dimension files for the QP levels declared in the project profile. LTM is the primary source for tooling standards at each level.

2. Validate pre-conditions

• Confirm quality-profile.yaml has at least one characteristic with relevance != not_applicable. Zero → structured failure with what_failed: empty_quality_profile.
• Confirm nfr-spec.yaml is present. Missing → structured failure with what_failed: missing_nfr_spec. NFR spec must precede quality vision — design_linkage cites NFR IDs.
• Confirm physical-architecture.yaml is present. Missing → structured failure with what_failed: missing_physical_architecture.

3. Enumerate characteristic entries

Build the complete list of ISO 25010 characteristics to cover. Every characteristic from quality-profile.yaml with relevance != not_applicable is mandatory. Characteristics with relevance = not_applicable are explicitly excluded and noted:

excluded_characteristics:
  - characteristic: portability
    reason: "quality-profile.portability.relevance = not_applicable — single-platform product"

For each mandatory characteristic, enumerate the decisions needed:

• Vision synthesis: what narrative statement explains why this characteristic matters for this product
• Target level: quantified (numeric, percentage, named standard) — echoed from quality-profile or adjusted
• Design linkage: which components and NFR entries deliver it
• Tooling: specific named tools with versions from the stack
• Thresholds: numeric gates (e.g., "80% coverage", "p95 ≤ 500ms", "zero critical vulnerabilities")
• Lifecycle gates: when CI / code review / monitoring enforces the threshold

Each of these fields except "echoed target" is an inferred decision — record in manifest.

4. For each characteristic: derive vision entry

Step 4a. Vision narrative. Write a 2-5 sentence narrative that explains why this characteristic is important for this specific product. Draw from:

• The quality-profile rationale field for this characteristic
• The product's epic success scenarios that depend on this characteristic
• The business risk of failing this characteristic (from epic failure scenarios)

Step 4b. Target level. Echo the intake target from quality-profile. If nfr-spec.yaml has adjusted the target for any NFR under this characteristic, note the adjustment and cite the NFR ID.

Step 4c. Design linkage. Identify which architectural elements deliver this characteristic:

• Logical component IDs from logical-architecture.yaml that are responsible
• NFR IDs from nfr-spec.yaml that address this characteristic
• Pattern references (forward-ref to design-patterns.yaml if applicable)

Step 4d. Tooling. Select specific named tools from the physical stack + LTM quality catalog at the declared QP level:

• Must use stack-consistent tooling (if backend is Node.js + TypeScript, don't prescribe pytest)
• Must name the tool and version (no "a linter", no "a test framework")
• Draw from physical-architecture.yaml:library_pins and observability for named products

Step 4e. Thresholds. Express every enforcement threshold as a measurable value:

• Coverage: "≥ 80% line coverage on new code"
• Performance: "p95 ≤ 500ms, p99 ≤ 1s at 100 concurrent users"
• Accessibility: "Lighthouse accessibility score ≥ 95; zero axe-core critical violations"
• Security: "Zero critical severity findings in SAST; zero known CVEs in production dependencies"

Step 4f. Lifecycle gates. State where and when each threshold is enforced:

• pre-commit hook, PR CI gate (blocking), nightly CI gate, pre-deploy gate, periodic audit
• Name the tool and the stage for each gate

5. Derive quality-vision.yaml

vision_statement — top-level narrative across all relevant characteristics:

vision_statement: >
  {A 3-5 sentence statement that synthesizes the quality direction for this product.
  Names the two or three most critical ISO 25010 characteristics for this product and why,
  and commits to how the architecture ensures they are delivered and enforced throughout
  the development lifecycle.}

characteristics — one entry per relevant ISO 25010 characteristic:

characteristics:
  - characteristic: performance_efficiency
    relevance: high      # echoed from quality-profile
    vision: >
      Users of this product are time-sensitive — checkout abandonment spikes when
      latency exceeds 800ms (EPIC-commerce-catalog failure scenario). Performance
      efficiency is the primary technical constraint that drove stack selection
      (SSR, edge caching, connection pooling) and must be continuously enforced
      to avoid silent regressions as feature count grows.
    target_level: "p95 API response ≤ 500ms; p95 page load ≤ 1.5s (Lighthouse LCP)"
    design_linkage:
      components: [comp-auth-service, comp-api-gateway]
      nfrs: [NFR-001]
      patterns: []  # populated when derive-design-patterns runs
    tooling:
      - name: "k6 OSS"
        version: "0.49.x"
        purpose: "API load testing — 100 VU ramp, p95 assertion"
        install_via: "npm"
      - name: "Lighthouse CI"
        version: "12.x"
        purpose: "Page load performance via LCP / FCP / CLS metrics"
        install_via: "npm"
    thresholds:
      - "API p95 response ≤ 500ms at 100 concurrent users"
      - "Page LCP ≤ 1.5s on simulated 4G (Lighthouse score ≥ 90 performance)"
       
    
        
         
         
        
         
         
        
         
         

    
     
          
    
       [, ]
       []
       []
    
        
         
         
         
        
         
         
        
         
         
        
         
         
         
    
       
       
       
       
    
        
         
         
        
         
         
        
         
         
        
         
         

    
     
          
    
       [, ]
       []
       []
    
        
         
         
         
        
         
         
         
        
         
         
         
        
         
         
    
       
       
       
       
       
    
        
         
         
        
         
         
        
         
         

6. Emit decision manifest

Write decision-manifest-derive-quality-vision.yaml to {decision_manifest_path} BEFORE writing the primary artifact.

Decisions to record (decision_id prefix: D-dqv-):

These decisions carry forward from the prior derive-quality-standards skill's D-dqs- decision set, renumbered to D-dqv-, and extended with vision-specific decisions:

decision_id	decision_type	What is being decided
D-dqv-001	tooling-variant-pick	When multiple tooling options are listed in LTM for the same QP dimension and level (e.g., Jest vs Vitest, Semgrep vs SonarCloud SAST), which is selected and why
D-dqv-002	threshold-adjustment	When an LTM baseline threshold is adjusted based on project profile risk appetite or epic failure scenarios (e.g., "≥80% line coverage" vs "≥75%"), the adjusted value and the driver
D-dqv-003	enforcement-venue-selection	For each gate, whether enforcement is "CI gate (blocking)", "CI gate (non-blocking)", "pre-commit hook", or "periodic audit" — and what drove the choice
D-dqv-004	iso-25010-mapping	How each standard is mapped to a specific ISO 25010 characteristic (e.g., "k6 load test → performance_efficiency")
D-dqv-005	gap-finalization	For each ISO 25010 characteristic from the quality profile, whether the standard set covers it completely or a gap exists, and the gap description if present
D-dqv-006	vision-narrative-synthesis	For each characteristic, the framing of the vision narrative — which driver (business risk, compliance mandate, user experience impact) is the lead sentence
D-dqv-007	design-linkage-mapping	How each characteristic is connected to specific logical components, NFR entries, and anticipated patterns — when the mapping requires reasoning rather than direct echo

schema_version: "1.0"
skill: "derive-quality-vision"
generated_at: "{ISO8601}"
decisions:
  - decision_id: "D-dqv-001"
    decision_type: "tooling-variant-pick"
    tier: high | mid | low
    grounding_source:
      kind: kb_path | web_citation | none
      ref: "{KB file path | URL | null}"
      excerpt: "{optional short quote when kind=kb_path}"
    recommendation: "{the tooling variant selected and the QP dimension it serves}"
    alternatives_considered:
      - alt: "{alternative tooling variant}"
        why_not: "{one-line dismissal reason}"
    agent_reasoning_summary: "{2-3 sentence explanation}"
    user_response: null
    user_response_detail: null
  # ... one entry per decision type, with additional entries per individual decision instance

7. Write primary artifact

Write quality-vision.yaml to {output_path}:

slug: "<from project_profile.name>"
status: DRAFT
created_at: "<ISO-8601>"
play: arch
skill: derive-quality-vision
upstream_artifacts:
  quality_profile_path: <echoed>
  nfr_spec_path: <echoed>
  logical_architecture_path: <echoed>
  physical_architecture_path: <echoed>
vision_statement: >
  ...
characteristics: [...]
excluded_characteristics: [...]
tooling_summary:
  - name: "Jest 29"
    purpose: "unit testing and coverage"
    install_via: "npm"
  - ...

8. Self-validation against constraints

Before returning:

• C7/F7: verify every characteristic from quality-profile.yaml with relevance != not_applicable has an entry in characteristics. Any missing characteristic → structured failure with what_failed: F7_orphan_characteristic and the characteristic name.
• C7/F7: verify every entry has ALL required fields populated: vision, target_level, design_linkage, tooling (non-empty list), thresholds (non-empty list), lifecycle_gates (non-empty list). Any empty field → structured failure with what_failed: F7_incomplete_entry.
• C8/F8: scan every tooling entry for vague language patterns: "a linter", "a test framework", "some monitoring tool", "thoroughly", "regularly". If any vague phrase found → structured failure with what_failed: F8_vague_tooling and the offending entry.
• C8/F8: scan every thresholds entry for non-quantified language: "good performance", "high coverage", "secure enough". If any non-quantified threshold found → structured failure with what_failed: F8_vague_threshold.
• F19: verify manifest has entries for all inferred decisions with tier, grounding_source, recommendation, and alternatives_considered populated.

9. Return output contract

quality_vision:
  path: <written path>
  vision_statement_present: true
  characteristics_covered: <int>
  characteristics_excluded: <int>
  total_profile_characteristics: <int>   # covered + excluded must equal this
  entries_with_complete_fields: <int>    # must equal characteristics_covered
  vague_language_violations: 0          # must be 0 — any > 0 triggers F8
  tooling_items_total: <int>
  lifecycle_gates_total: <int>
decision_manifest:
  path: <written path>
  decisions_recorded: <int>

Outputs

outputs:
  - path: "{product_base}architecture/quality-vision.yaml"
    required: true
  - path: "{product_base}architecture/decision-manifest-derive-quality-vision.yaml"
    required: true

Constraints

• NEVER skip a relevant ISO 25010 characteristic. Every characteristic from the quality profile with relevance != not_applicable must have an entry. Orphan characteristics are F7 violations.
• NEVER use vague language. "Use a linter" is invalid; "ESLint 8 with Airbnb config + import/no-restricted-paths" is valid. "Test thoroughly" is invalid; "Jest 29 with ≥80% line coverage on new code, CI blocking gate on PR" is valid. This is F8.
• NEVER omit enforcement / lifecycle_gates. Standards without gates are aspirations, not architecture.
• NEVER propose tooling that contradicts the physical stack. If the backend is Node.js + TypeScript, do not prescribe pytest or coverage.py.
• ALWAYS include design_linkage per entry — this is the merge contribution that separates quality-vision from quality-standards. Every characteristic must trace to at least one component or NFR ID.
• ALWAYS include drivers for security-critical and performance-critical entries — auditors expect to trace from standard to business requirement.
• ALWAYS write the manifest before writing the primary artifact.
• NEVER commit an inferred decision to quality-vision.yaml without recording it in the decision manifest first.
• NEVER tag a decision tier: high unless the grounding_source.kind is kb_path AND the referenced KB file exists.
• ALWAYS include alternatives_considered with at least one entry per decision. If genuinely no alternative, state "none — only candidate" explicitly.
• NEVER emit source_type: agent_default_unilateral.
• Read LTM quality knowledge first for tooling standards at each QP level. Use the declared QP dimensions from project-profile.yaml to select the appropriate standard level.

DSD Compliance (C18/C19)

This skill emits a decision manifest alongside its primary artifact. Every inferred decision (not user-provided input) lands in the manifest with tier, grounding_source, recommendation, alternatives_considered, and user_response=null. The orchestrator walks the manifest after this skill completes and drives the tiered surfacing flow before downstream skills read the primary artifact. A manifest-free emission is a structural violation (F19).

Version

Field	Value
Version	0.1.0
Category	architecture
Created	2026-04-15
Related	core/components/agents/tech-designer.md, core/components/skills/derive-nfr-spec, core/components/memory/knowledge/quality/