dew-method 0.1.0

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/assets/kpi-feasibility-report-template.md

@@ -0,0 +1,163 @@
+# KPI Feasibility Report Template
+
+```markdown
+---
+title: "{Project Name} KPI Feasibility Report"
+status: draft
+created: {YYYY-MM-DD}
+updated: {YYYY-MM-DD}
+workflow: dew
+phase: "2-plan-workflows"
+stepsCompleted: []
+decisionGates:
+  GATE-06-kpi-feasibility:
+    status: pending
+evidence: []
+assumptions: []
+caveats:
+  - "A KPI is not verified unless field availability, grain compatibility, and sample computation are supported by evidence."
+---
+
+# KPI Feasibility Report: {Project Name}
+
+## 0. Document Purpose
+
+This report evaluates whether candidate KPIs can be computed from available data.
+
+It does not design architecture.
+
+Architecture may start only after primary KPI feasibility is verified or explicitly caveated.
+
+## 1. Input Artifacts
+
+| Artifact | Path | Loaded? | Notes |
+|---|---|---|---|
+| Project Brief | | Yes/No | |
+| Business Discovery | | Yes/No | |
+| KPI Catalog | | Yes/No | |
+| KPI Source Matrix | | Yes/No | |
+| Data Product PRD | | Yes/No | |
+| Decision Log | | Yes/No | |
+| Evidence Index | | Yes/No | |
+
+## 2. KPI Feasibility Summary
+
+| KPI ID | KPI Name | Priority | Current Status | Recommended Status | Decision Needed |
+|---|---|---|---|---|---|
+| KPI-001 | | Primary/Secondary | Hypothesis | | Yes/No |
+
+## 3. KPI Detail
+
+## KPI-001 — {KPI Name}
+
+### Business Question
+
+### Decision Supported
+
+### Consumer
+
+### Formula
+
+### Target Grain
+
+### Required Fields
+
+| Required Field | Meaning | Candidate Source | Source Field | Field Available? | Evidence |
+|---|---|---|---|---|---|
+| | | | | Unknown/Yes/No | |
+
+### Grain Compatibility
+
+Target KPI grain:
+
+Candidate source grain:
+
+Compatibility:
+- Compatible
+- Requires aggregation
+- Requires join/bridge
+- Incompatible
+- Unknown
+
+Evidence:
+
+### Sample Computation Requirement
+
+Required prototype type:
+- SQL
+- Python
+- Notebook
+- Manual calculation
+- Not possible yet
+
+Prototype path:
+
+Sample output path:
+
+### Data Quality Checks Needed
+
+- not_null:
+- valid_range:
+- duplicate check:
+- freshness:
+- referential integrity:
+- business rule consistency:
+
+### Feasibility Status
+
+Choose one:
+
+- Verified on sample
+- Feasible with caveats
+- Hypothesis only
+- Deferred
+- Rejected
+
+Current:
+
+### Caveats
+
+### Decision Required
+
+A. Accept as feasible on sample  
+B. Accept with caveats  
+C. Keep as hypothesis  
+D. Defer from MVP  
+E. Reject KPI  
+
+### User Decision
+
+## 4. KPI Feasibility Matrix
+
+| KPI ID | Required Fields Verified? | Grain Compatible? | Sample Computed? | Output Reviewed? | Final Status |
+|---|---|---|---|---|---|
+| KPI-001 | No | Unknown | No | No | Hypothesis only |
+
+## 5. Architecture Readiness Impact
+
+Can architecture proceed?
+
+A. Yes  
+B. Yes, with caveats  
+C. No, return to KPI feasibility  
+D. Reduce MVP scope  
+
+Decision:
+
+## 6. Open Issues
+
+## 7. Evidence Links
+
+| Evidence ID | Type | Path | Related KPI | Status |
+|---|---|---|---|---|
+| EVD-001 | | | | |
+
+## 8. Next Workflow
+
+Required next:
+- `dew-kpi-prototype`
+- `dew-kpi-validation-review`
+
+Then:
+- `dew-source-validation`
+- `dew-requirement-gate`

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/assets/kpi-feasibility-status-rubric.md

@@ -0,0 +1,52 @@
+# KPI Feasibility Status Rubric
+
+## Status: Verified on sample
+
+Use when:
+- required fields are available in sample
+- field meanings are plausible
+- grain is compatible or transformation is clear
+- sample computation was executed
+- sample output was reviewed
+- caveats are documented
+
+This does not mean production-ready.
+
+## Status: Feasible with caveats
+
+Use when:
+- KPI can likely be computed
+- some limitations exist
+- user approves caveated continuation
+- downstream artifacts will preserve caveats
+
+Examples:
+- sample is small
+- source freshness is uncertain
+- field meaning needs owner confirmation
+- source coverage is partial
+
+## Status: Hypothesis only
+
+Use when:
+- KPI is defined
+- but field availability or sample computation has not been proven
+
+This status blocks architecture for primary KPI unless user explicitly approves caveated continuation.
+
+## Status: Deferred
+
+Use when:
+- KPI is useful
+- but not needed for MVP
+- or source is not currently available
+- or validation cost is too high for now
+
+## Status: Rejected
+
+Use when:
+- KPI cannot be computed from available data
+- formula is not meaningful
+- grain is incompatible
+- required source does not exist
+- user decides not to pursue it

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/assets/sample-computation-plan-template.md

@@ -0,0 +1,43 @@
+
+---
+
+## `assets/sample-computation-plan-template.md`
+
+```markdown
+# Sample Computation Plan Template
+
+```markdown
+# KPI Sample Computation Plan
+
+## KPI
+
+KPI ID:
+
+KPI Name:
+
+## Goal
+
+Compute the KPI on a small validated sample to prove basic feasibility.
+
+## Inputs
+
+| Input | Path / Source | Required? | Available? |
+|---|---|---|---|
+| Source sample | | Yes | Unknown |
+| Schema snapshot | | Yes | Unknown |
+| Field mapping | | Yes | Unknown |
+
+## Computation Method
+
+Choose one:
+
+- SQL
+- Python
+- Notebook
+- Manual calculation
+- Not possible yet
+
+## Formula
+
+```text
+{formula}

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/checklist.md

@@ -0,0 +1,41 @@
+# KPI Feasibility Checklist
+
+## Required inputs
+
+- [ ] Project brief loaded or context provided.
+- [ ] Business discovery loaded or context provided.
+- [ ] KPI catalog loaded.
+- [ ] KPI-source matrix loaded.
+- [ ] Data product PRD loaded or caveat recorded.
+- [ ] Decision log loaded if available.
+- [ ] Evidence index loaded if available.
+
+## KPI definition checks
+
+- [ ] KPI has ID.
+- [ ] KPI has name.
+- [ ] KPI maps to business question.
+- [ ] KPI maps to consumer.
+- [ ] KPI has formula.
+- [ ] KPI has target grain.
+- [ ] KPI lists required fields.
+- [ ] KPI lists candidate source dependencies.
+
+## Feasibility checks
+
+- [ ] Required fields checked.
+- [ ] Field meanings checked or marked unknown.
+- [ ] Grain compatibility assessed.
+- [ ] Sample computation plan created.
+- [ ] Prototype requirement assigned.
+- [ ] Feasibility status assigned.
+- [ ] Caveats documented.
+- [ ] User decision captured for primary KPIs.
+
+## Evidence discipline
+
+- [ ] KPI is not marked verified without sample computation.
+- [ ] Missing evidence triggers HALT-03 or HALT-18.
+- [ ] Evidence index updated if evidence exists.
+- [ ] Decision log updated.
+- [ ] Learning log updated if learning mode is enabled.

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for dew-kpi-feasibility.
+#
+# Override files:
+#   {project-root}/_dew/custom/dew-kpi-feasibility.toml
+#   {project-root}/_dew/custom/dew-kpi-feasibility.user.toml
+
+[workflow]
+
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+  "file:{project-root}/**/brief.md",
+  "file:{project-root}/**/business-discovery.md",
+  "file:{project-root}/**/kpi-catalog.md",
+  "file:{project-root}/**/kpi-source-matrix.md",
+  "file:{project-root}/**/data-product-prd.md",
+  "file:{project-root}/**/.decision-log.md",
+  "file:{project-root}/**/.learning-log.md",
+  "file:{project-root}/**/validation-evidence-index.md",
+]
+
+on_complete = ""
+
+feasibility_report_template = "assets/kpi-feasibility-report-template.md"
+field_availability_template = "assets/field-availability-template.md"
+sample_computation_plan_template = "assets/sample-computation-plan-template.md"
+status_rubric = "assets/kpi-feasibility-status-rubric.md"
+checklist = "checklist.md"
+
+feasibility_output_path = "{planning_artifacts}/kpi-feasibility"
+run_folder_pattern = "kpi-feasibility-{project_name}-{date}"
+
+decision_log_path = "{planning_artifacts}/.decision-log.md"
+learning_log_path = "{learning_artifacts}/.learning-log.md"
+evidence_index_path = "{evidence_artifacts}/validation-evidence-index.md"
+
+prototype_output_path = "{evidence_artifacts}/kpi-feasibility"

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/steps/step-01-init.md

@@ -0,0 +1,54 @@
+# Step 01 — KPI Feasibility Initialization
+
+## Mandatory Rules
+
+- Do not create final architecture.
+- Do not mark any KPI as verified in this step.
+- Do not proceed if KPI catalog is missing unless the user explicitly provides KPI context.
+- Read the complete step before acting.
+- Initialize document state before moving to next step.
+
+## Task
+
+Initialize KPI feasibility workflow.
+
+## Sequence
+
+### 1. Detect existing workflow
+
+Look for existing KPI feasibility report in:
+
+- `{workflow.feasibility_output_path}/**/kpi-feasibility-report.md`
+- `{planning_artifacts}/**/*kpi*feasibility*.md`
+
+If an unfinished report exists, offer to resume.
+
+### 2. Create workspace
+
+If fresh workflow, bind `{doc_workspace}` to:
+
+`{workflow.feasibility_output_path}/{workflow.run_folder_pattern}/`
+
+Create:
+
+- `kpi-feasibility-report.md`
+- `field-availability.md`
+- `sample-computation-plan.md`
+
+Use templates:
+
+- `{workflow.feasibility_report_template}`
+- `{workflow.field_availability_template}`
+- `{workflow.sample_computation_plan_template}`
+
+### 3. Initialize frontmatter
+
+Set:
+
+```yaml
+status: draft
+stepsCompleted:
+  - step-01-init
+decisionGates:
+  GATE-06-kpi-feasibility:
+    status: pending

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/steps/step-02-load-kpi-context.md

@@ -0,0 +1,61 @@
+# Step 02 — Load KPI Context
+
+## Mandatory Rules
+
+- Load all available KPI context before evaluating feasibility.
+- Do not infer missing KPI formula or grain silently.
+- If formula, grain, or required fields are missing, trigger `HALT-02 — KPI Definition Unverified`.
+
+## Task
+
+Load and summarize KPI context from prior artifacts.
+
+## Input discovery
+
+Search for:
+
+- `{planning_artifacts}/**/kpi-catalog.md`
+- `{planning_artifacts}/**/kpi-source-matrix.md`
+- `{planning_artifacts}/**/business-discovery.md`
+- `{planning_artifacts}/**/data-product-prd.md`
+- `{planning_artifacts}/**/.decision-log.md`
+- `{learning_artifacts}/**/.learning-log.md`
+
+## Extract
+
+For each KPI:
+
+- KPI ID
+- KPI name
+- business question
+- decision supported
+- consumer
+- formula
+- target grain
+- dimensions
+- required fields
+- candidate sources
+- current status
+
+## Validate minimum definition
+
+A KPI is minimally defined only if it has:
+
+- formula
+- grain
+- required fields
+- business question
+- consumer
+
+If missing, stop and trigger `HALT-02`.
+
+## Update report
+
+Append context summary to `kpi-feasibility-report.md`.
+
+Update frontmatter:
+
+```yaml
+stepsCompleted:
+  - step-01-init
+  - step-02-load-kpi-context

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/steps/step-03-field-availability.md

@@ -0,0 +1,67 @@
+# Step 03 — Field Availability Analysis
+
+## Mandatory Rules
+
+- Do not assume required fields exist.
+- Do not assume candidate source field names are correct.
+- If no sample/schema/source evidence exists, mark field availability as Unknown.
+- Unknown field availability blocks KPI verification.
+
+## Task
+
+Assess whether required KPI fields are available in candidate sources.
+
+## For each KPI
+
+Create a field availability table:
+
+| Required Field | Business Meaning | Candidate Source | Candidate Source Field | Available? | Evidence |
+|---|---|---|---|---|---|
+
+## Evidence types allowed
+
+- source sample
+- schema snapshot
+- field dictionary
+- API response
+- CSV header
+- database schema
+- notebook inspection
+- documented source specification
+
+## Classification
+
+Field availability must be one of:
+
+- Yes
+- No
+- Unknown
+- Partial
+- Substitute available
+
+## Missing field handling
+
+If a required field is missing:
+
+Options:
+A. Find substitute field  
+B. Modify KPI formula  
+C. Defer KPI  
+D. Reject KPI  
+
+Ask user if the field is critical.
+
+## Update files
+
+Update:
+
+- `field-availability.md`
+- `kpi-feasibility-report.md`
+
+Update frontmatter:
+
+```yaml
+stepsCompleted:
+  - step-01-init
+  - step-02-load-kpi-context
+  - step-03-field-availability

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/steps/step-04-computation-plan.md

@@ -0,0 +1,60 @@
+# Step 04 — Sample Computation Plan
+
+## Mandatory Rules
+
+- Do not mark KPI feasible before sample computation.
+- Do not design production transformation here.
+- The goal is proving feasibility on sample, not building the final pipeline.
+
+## Task
+
+Create a sample computation plan for each primary KPI.
+
+## For each KPI
+
+Define:
+
+- prototype method: SQL / Python / notebook / manual / not possible yet
+- input sample needed
+- formula implementation
+- target grain
+- validation checks
+- expected output columns
+- evidence to produce
+
+## Computation readiness
+
+Classify each KPI:
+
+- Ready for prototype
+- Needs source sample
+- Needs schema snapshot
+- Needs field mapping
+- Needs formula revision
+- Not ready
+
+## Required output
+
+Update:
+
+- `sample-computation-plan.md`
+- `kpi-feasibility-report.md`
+
+## Next implementation skill
+
+If at least one KPI is ready for prototype, recommend:
+
+`dew-kpi-prototype`
+
+If no KPI is ready, trigger:
+
+`HALT-03 — KPI Feasibility Not Proven`
+
+## Update frontmatter
+
+```yaml
+stepsCompleted:
+  - step-01-init
+  - step-02-load-kpi-context
+  - step-03-field-availability
+  - step-04-computation-plan

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/steps/step-05-feasibility-gate.md

@@ -0,0 +1,60 @@
+# Step 05 — KPI Feasibility Gate
+
+## Mandatory Rules
+
+- Stop at this gate.
+- Present evidence and missing evidence.
+- Recommend status, but do not decide.
+- User must approve final status for primary KPIs.
+
+## Task
+
+Run GATE-06 — KPI Feasibility Gate.
+
+## Status options
+
+For each KPI, choose one:
+
+A. Verified on sample  
+B. Feasible with caveats  
+C. Hypothesis only  
+D. Deferred  
+E. Rejected  
+
+## Gate explanation
+
+Explain:
+
+- why KPI feasibility matters
+- how unverified KPI causes architecture hallucination
+- how field availability affects transformation
+- how grain mismatch affects Gold models and serving
+- what evidence is still missing
+
+## Required table
+
+| KPI ID | Field Availability | Grain Compatibility | Prototype Ready? | Evidence | Recommended Status |
+|---|---|---|---|---|---|
+
+## User decision
+
+Ask the user to approve status for each primary KPI.
+
+Do not continue until user chooses.
+
+## Decision log
+
+Record each primary KPI decision in `.decision-log.md`.
+
+## Learning log
+
+If learning mode is enabled, record what was learned about KPI feasibility.
+
+## Update frontmatter
+
+Update:
+
+```yaml
+decisionGates:
+  GATE-06-kpi-feasibility:
+    status: approved / approved-with-caveats / blocked

package/src/dew-skills/2-plan-workflows/dew-kpi-feasibility/steps/step-06-finalize.md

@@ -0,0 +1,48 @@
+# Step 06 — Finalize KPI Feasibility Report
+
+## Mandatory Rules
+
+- Do not finalize if primary KPI status is still Hypothesis only unless user explicitly approved caveated continuation.
+- Do not mark architecture ready unless KPI feasibility gate is approved or approved-with-caveats.
+- Evidence must be indexed if it exists.
+
+## Task
+
+Finalize KPI feasibility report.
+
+## Checklist
+
+Run `checklist.md`.
+
+## Required final outputs
+
+- `kpi-feasibility-report.md`
+- `field-availability.md`
+- `sample-computation-plan.md`
+- decision log entry
+- learning log entry
+- evidence index update if evidence exists
+
+## Architecture readiness status
+
+Choose one:
+
+A. Architecture can proceed after source validation  
+B. Architecture can proceed with KPI caveats after source validation  
+C. Architecture cannot proceed; KPI feasibility unresolved  
+D. Reduce MVP scope  
+
+## Final status
+
+Set report frontmatter:
+
+```yaml
+status: final
+updated: {date}
+stepsCompleted:
+  - step-01-init
+  - step-02-load-kpi-context
+  - step-03-field-availability
+  - step-04-computation-plan
+  - step-05-feasibility-gate
+  - step-06-finalize