dew-method 0.1.0

package/src/dew-skills/1-analysis/dew-halt-resolver/assets/halt-template.md

@@ -0,0 +1,91 @@
+# HALT-XX — {Halt Name}
+
+## Type
+
+Soft Halt / Hard Halt / Safety Halt / Readiness Halt
+
+## Trigger
+
+This HALT is triggered when:
+- ...
+
+## Why this matters
+
+Explain why continuing would create risk, ambiguity, or hallucination.
+
+Connect to the data engineering lifecycle:
+- Generation / Source Systems:
+- Storage:
+- Ingestion:
+- Transformation:
+- Serving:
+- Undercurrents:
+
+## Current state
+
+What is known:
+- ...
+
+What is unknown:
+- ...
+
+What is assumed:
+- ...
+
+## Missing evidence
+
+- ...
+
+## Risk if ignored
+
+If the workflow continues without resolving this HALT:
+- ...
+
+## Options
+
+### A. Resolve now
+
+Do:
+- ...
+
+### B. Continue with caveat
+
+Allowed only if:
+- user approves
+- caveat is recorded
+- downstream impact is documented
+
+### C. Reduce scope
+
+Remove or defer the risky item.
+
+### D. Stop / return to previous phase
+
+Return to:
+- ...
+
+## Recommendation
+
+Recommended option: {A/B/C/D}
+
+Reason:
+- ...
+
+## Required user decision
+
+Please choose:
+- A
+- B
+- C
+- D
+- E = explain more
+- R = revise options
+
+## Resume condition
+
+The workflow may resume only when:
+- user has made a decision
+- `.decision-log.md` is updated
+- `.learning-log.md` is updated
+- required evidence is produced or caveat is approved
+- current artifact frontmatter is updated

package/src/dew-skills/1-analysis/dew-halt-resolver/checklist.md

@@ -0,0 +1,35 @@
+# HALT Resolution Checklist
+
+Use this checklist before resuming from a HALT.
+
+## Required
+
+- [ ] HALT ID is identified.
+- [ ] HALT type is identified.
+- [ ] Trigger is documented.
+- [ ] Risk is explained.
+- [ ] Missing evidence is listed.
+- [ ] Options are provided.
+- [ ] Recommendation is provided.
+- [ ] User chooses a resolution.
+- [ ] Decision log is updated.
+- [ ] Learning log is updated.
+- [ ] Evidence is produced or caveat is approved.
+- [ ] Current artifact frontmatter is updated.
+- [ ] Resume condition is met.
+
+## Allowed resolution states
+
+- resolved
+- resolved-with-caveat
+- deferred
+- returned-to-previous-phase
+- scope-reduced
+- blocked
+
+## Not allowed
+
+- resume without user decision
+- resume without decision log
+- resume with missing evidence unless caveat is explicitly approved
+- mark phase complete with unresolved hard halt

package/src/dew-skills/1-analysis/dew-halt-resolver/customize.toml

@@ -0,0 +1,25 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for dew-halt-resolver.
+
+[workflow]
+
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+  "file:{project-root}/**/.decision-log.md",
+  "file:{project-root}/**/.learning-log.md",
+]
+
+on_complete = ""
+
+halt_template = "assets/halt-template.md"
+halt_catalog = "assets/halt-catalog.md"
+halt_resolution_template = "assets/halt-resolution-template.md"
+checklist = "checklist.md"
+
+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"

package/src/dew-skills/1-analysis/dew-kpi-discovery/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: dew-kpi-discovery
+description: Define candidate KPIs, formulas, grains, required fields, and source dependencies without claiming feasibility.
+---
+
+# DEW KPI Discovery
+
+**Goal:** Convert business questions into candidate KPI definitions that can later be validated.
+
+**Your Role:** You are a KPI discovery facilitator and data analyst.
+
+You help define KPIs clearly, but you must not claim they are feasible until Batch 3 validates them with real data.
+
+## Mandatory Rules
+
+- KPI definitions are hypotheses until validated.
+- Do not mark KPI as verified.
+- Do not assume source fields exist.
+- Do not assume source grain matches KPI grain.
+- If formula/grain/required fields are missing, trigger `HALT-02 — KPI Definition Unverified`.
+- If user asks to proceed to architecture, remind them that KPI feasibility must be validated first.
+
+## On Activation
+
+1. Resolve customization.
+2. Execute `{workflow.activation_steps_prepend}`.
+3. Load persistent facts.
+4. Load config if present.
+5. Load:
+   - `{workflow.kpi_catalog_template}`
+   - `{workflow.kpi_definition_rubric}`
+   - `{workflow.kpi_source_matrix_template}`
+6. Greet user in configured language.
+
+## Execution
+
+### Step 1 — Load Business Discovery
+
+Look for:
+- `{planning_artifacts}/business-discovery/**/business-discovery.md`
+- `{planning_artifacts}/**/*business*.md`
+- `{planning_artifacts}/**/*brief*.md`
+
+If missing, ask user to run `dew-business-discovery` or provide context.
+
+### Step 2 — Extract Business Questions
+
+Extract:
+- consumer
+- question
+- decision supported
+- action taken
+- expected output
+
+### Step 3 — Propose KPI Candidates
+
+For each business question, propose KPI candidates.
+
+Each KPI must include:
+- KPI ID
+- KPI name
+- business question
+- decision supported
+- formula
+- grain
+- dimensions
+- required fields
+- candidate source dependency
+- feasibility status = Hypothesis
+
+### Step 4 — KPI Definition Gate
+
+For each primary KPI, ask user to approve definition:
+
+A. Accept KPI definition as hypothesis  
+B. Revise formula  
+C. Revise grain  
+D. Defer KPI  
+
+Do not continue until user chooses.
+
+### Step 5 — Source Dependency Mapping
+
+Create KPI-source matrix.
+
+Important:
+- source dependency is candidate only
+- source availability is not verified
+- field existence is not verified
+
+### Step 6 — Finalize
+
+Create:
+
+`{workflow.kpi_output_path}/{workflow.run_folder_pattern}/kpi-catalog.md`
+
+Also create:
+
+`kpi-source-matrix.md`
+
+Recommend next:
+
+`dew-data-product-prd`
+
+Then Batch 3:
+
+`dew-kpi-feasibility`

package/src/dew-skills/1-analysis/dew-kpi-discovery/assets/kpi-catalog-template.md

@@ -0,0 +1,110 @@
+# KPI Catalog Template
+
+```markdown
+---
+title: "{Project Name} KPI Catalog"
+status: draft
+created: {YYYY-MM-DD}
+updated: {YYYY-MM-DD}
+workflow: dew
+phase: "1-analysis"
+decisionGates:
+  GATE-03-kpi-definition:
+    status: pending
+  GATE-04-kpi-grain:
+    status: pending
+evidence: []
+assumptions: []
+caveats:
+  - "KPIs are hypotheses until validated by dew-kpi-feasibility."
+---
+
+# KPI Catalog: {Project Name}
+
+## 0. Important Status Note
+
+All KPIs in this document are candidate KPIs.
+
+They are not verified until Batch 3 KPI Feasibility validates them with real source/sample data.
+
+## 1. KPI Summary
+
+| KPI ID | KPI Name | Business Question | Consumer | Status |
+|---|---|---|---|---|
+| KPI-001 | | | | Hypothesis |
+
+## 2. KPI Details
+
+## KPI-001 — {KPI Name}
+
+### Business Question
+
+### Decision Supported
+
+### Consumer
+
+### Formula
+
+### Grain
+
+One row represents:
+
+### Dimensions
+
+- Time:
+- Geography:
+- Entity:
+- Category:
+
+### Required Fields
+
+| Field | Meaning | Required? | Candidate Source | Verified? |
+|---|---|---|---|---|
+| | | Yes/No | | No |
+
+### Candidate Sources
+
+| Source ID | Source Name | Source Type | Dependency Type | Verified? |
+|---|---|---|---|---|
+| SRC-001 | | API/File/DB | Required/Optional | No |
+
+### Feasibility Status
+
+Choose one:
+
+- Hypothesis
+- Needs source validation
+- Needs field validation
+- Deferred
+- Rejected
+
+Current status: Hypothesis
+
+### Assumptions
+
+- [ASSUMPTION] ...
+
+### Caveats
+
+- ...
+
+### Evidence Links
+
+Do not add evidence unless it exists.
+
+- Field availability:
+- Sample computation:
+- Sample output:
+- Validation report:
+
+## 3. Open KPI Questions
+
+## 4. Next Workflow
+
+Recommended next:
+
+`dew-data-product-prd`
+
+Required later:
+
+`dew-kpi-feasibility`

package/src/dew-skills/1-analysis/dew-kpi-discovery/assets/kpi-definition-rubric.md

@@ -0,0 +1,42 @@
+# KPI Definition Rubric
+
+A KPI is well-defined when it has:
+
+## Required
+
+- KPI ID
+- KPI name
+- business question
+- decision supported
+- consumer
+- formula
+- grain
+- dimensions
+- required fields
+- candidate source dependency
+- feasibility status
+
+## Strong KPI Definition
+
+A strong KPI definition answers:
+
+1. What does this metric measure?
+2. Who uses it?
+3. What decision does it support?
+4. What is the formula?
+5. What is the grain?
+6. What dimensions are needed?
+7. What fields are required?
+8. Which source may provide those fields?
+9. What assumptions exist?
+10. What must be validated later?
+
+## Failure Conditions
+
+A KPI definition fails if:
+- formula is missing
+- grain is missing
+- required fields are missing
+- source dependency is unknown
+- it is marked verified without evidence
+- it does not map to a business decision

package/src/dew-skills/1-analysis/dew-kpi-discovery/assets/kpi-source-matrix-template.md

@@ -0,0 +1,5 @@
+# KPI Source Matrix
+
+| KPI ID | KPI Name | Required Field | Candidate Source | Source Field | Field Verified? | Grain Match? | Notes |
+|---|---|---|---|---|---|---|
+| KPI-001 | | | SRC-001 | | No | Unknown | |

package/src/dew-skills/1-analysis/dew-kpi-discovery/checklist.md

@@ -0,0 +1,16 @@
+# KPI Discovery Checklist
+
+- [ ] Business discovery loaded or context provided.
+- [ ] Business questions extracted.
+- [ ] KPI candidates proposed.
+- [ ] Each KPI has an ID.
+- [ ] Each KPI maps to a business question.
+- [ ] Each KPI has a formula.
+- [ ] Each KPI has a grain.
+- [ ] Each KPI lists required fields.
+- [ ] Each KPI lists candidate source dependencies.
+- [ ] Feasibility status is not marked verified.
+- [ ] Assumptions are labeled.
+- [ ] KPI-source matrix created.
+- [ ] Decision log updated.
+- [ ] Learning log updated if learning mode is enabled.

package/src/dew-skills/1-analysis/dew-kpi-discovery/customize.toml

@@ -0,0 +1,29 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for dew-kpi-discovery.
+
+[workflow]
+
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+  "file:{project-root}/**/business-discovery.md",
+  "file:{project-root}/**/brief.md",
+  "file:{project-root}/**/.decision-log.md",
+  "file:{project-root}/**/.learning-log.md",
+]
+
+on_complete = ""
+
+kpi_catalog_template = "assets/kpi-catalog-template.md"
+kpi_definition_rubric = "assets/kpi-definition-rubric.md"
+kpi_source_matrix_template = "assets/kpi-source-matrix-template.md"
+checklist = "checklist.md"
+
+kpi_output_path = "{planning_artifacts}/kpi-discovery"
+run_folder_pattern = "kpi-discovery-{project_name}-{date}"
+
+decision_log_path = "{planning_artifacts}/.decision-log.md"
+learning_log_path = "{learning_artifacts}/.learning-log.md"

package/src/dew-skills/1-analysis/dew-project-brief/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: dew-project-brief
+description: Create, update, or validate a DEW project brief focused on data engineering scope, business purpose, learning objective, and evidence-driven continuation.
+---
+
+# DEW Project Brief
+
+**Goal:** Create a concise but decision-ready project brief for a data engineering project.
+
+**Your Role:** You are a DEW facilitator. You help the user clarify project purpose, scope, learning goals, expected data product, and evidence requirements.
+
+You may recommend, but you must not decide.
+
+## Conventions
+
+- Bare paths resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{workflow.<name>}` resolves to fields in `customize.toml`'s `[workflow]` table.
+- `{doc_workspace}` is the run folder for this brief.
+
+## Mandatory Rules
+
+- Do not write a final brief before project scope is clear.
+- Do not treat KPI/source assumptions as facts.
+- If the project has no clear consumer or decision, trigger `HALT-01 — Business Decision Unclear`.
+- Record project-shaping decisions in `.decision-log.md`.
+- If learning mode is enabled, explain the relevant data engineering concepts.
+
+## On Activation
+
+1. Resolve customization:
+
+   `python3 {project-root}/_dew/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+   If the script fails, read `{skill-root}/customize.toml` directly and use defaults.
+
+2. Execute `{workflow.activation_steps_prepend}`.
+
+3. Load persistent facts from `{workflow.persistent_facts}`.
+
+4. Load `{project-root}/_dew/dew/config.yaml` if present and resolve:
+   - `{user_name}`
+   - `{project_name}`
+   - `{communication_language}`
+   - `{document_output_language}`
+   - `{planning_artifacts}`
+   - `{learning_artifacts}`
+   - `{learning_mode}`
+
+5. Load:
+   - `{workflow.brief_template}`
+   - `{workflow.validation_rubric}`
+
+6. Greet user in `{communication_language}`.
+
+## Intent Modes
+
+### Create
+
+Create a new project brief.
+
+Bind `{doc_workspace}` to:
+
+`{workflow.brief_output_path}/{workflow.run_folder_pattern}/`
+
+Create:
+- `brief.md`
+- `.decision-log.md` if missing
+- `addendum.md` when useful
+
+### Update
+
+Update an existing project brief based on a change signal.
+
+Before editing:
+- read the existing brief
+- read `.decision-log.md`
+- identify conflicts with prior decisions
+- ask user to approve project-shaping changes
+
+### Validate
+
+Critique an existing project brief against the validation rubric.
+
+Do not modify the brief unless the user asks.
+
+## Discovery
+
+Start with a broad project dump.
+
+Ask for:
+- project idea
+- target user
+- business or learning goal
+- expected data product
+- domain
+- known sources
+- known KPIs
+- constraints
+- intended platform/tools, if any
+
+Then classify the project:
+
+A. Learning / exploration  
+B. Portfolio project  
+C. Internal decision-support  
+D. Production-grade  
+
+This is a decision gate. Do not continue until the user chooses.
+
+## Required Brief Sections
+
+Use `{workflow.brief_template}` as a starting point, not a rigid contract.
+
+The brief must include:
+- project purpose
+- target users / consumers
+- decision supported
+- expected data product
+- MVP scope
+- non-goals
+- learning objectives
+- initial KPI hypotheses
+- initial source hypotheses
+- assumptions
+- evidence required before architecture
+- next workflow recommendation
+
+## Finalize
+
+Before marking the brief as final:
+
+1. Run the checklist.
+2. Ensure project scope gate is resolved.
+3. Ensure unknowns are labeled.
+4. Ensure assumptions are not presented as facts.
+5. Update `.decision-log.md`.
+6. Update `.learning-log.md` if learning mode is enabled.
+7. Set frontmatter `status: final`.
+8. Recommend next skill: `dew-business-discovery`.