@tyroneross/build-loop 0.30.3 → 0.35.0

package/skills/loop-builder/presets/presentation-audit.yaml

@@ -0,0 +1,96 @@
+{
+  "id": "presentation-audit",
+  "title": "Presentation Audit Loop",
+  "summary": "Audit a deck for storyline, evidence, slide-level clarity, accessibility, and prioritized fixes.",
+  "inputs": [
+    "pptx or pdf",
+    "speaker notes",
+    "audience",
+    "meeting goal",
+    "source material"
+  ],
+  "outputs": [
+    "slide inventory",
+    "audit report",
+    "prioritized fix plan",
+    "claim/source map",
+    "reusable deck failure patterns"
+  ],
+  "phases": {
+    "assess": {
+      "goal": "Extract deck inventory and define audience, decision, timebox, and intended outcome.",
+      "required": ["deck_inventory", "audience", "decision_or_goal", "source_material"]
+    },
+    "plan": {
+      "goal": "Choose audit lenses and order deterministic checks before judgment checks.",
+      "required": ["audit_lenses", "slide_reference_scheme", "accessibility_scope"]
+    },
+    "produce": {
+      "goal": "Produce findings with slide references and ranked fixes.",
+      "required": ["slide_findings", "claim_gaps", "fix_priority"]
+    },
+    "review": {
+      "goal": "Check that findings are specific, evidenced, and separated by severity and type.",
+      "required": ["finding_evidence", "severity_ranking", "accessibility_split"]
+    },
+    "learn": {
+      "goal": "Capture recurring deck failure modes and reusable slide patterns.",
+      "required": ["failure_patterns", "template_candidates"]
+    }
+  },
+  "validators": [
+    {
+      "id": "slide_references",
+      "pass_condition": "Every finding cites a slide number, section, or notes location.",
+      "method": "review"
+    },
+    {
+      "id": "claim_support",
+      "pass_condition": "Material claims are mapped to a source or marked as unsupported/assumption.",
+      "method": "review"
+    },
+    {
+      "id": "audience_fit",
+      "pass_condition": "Recommendations are tied to the audience job and meeting decision, not taste alone.",
+      "method": "review"
+    },
+    {
+      "id": "accessibility_split",
+      "pass_condition": "Accessibility findings are separated from storyline/design judgment and labeled partial when automated extraction is limited.",
+      "method": "review"
+    }
+  ],
+  "gates": {
+    "confirm": ["external_send", "sensitive_data_exposure"],
+    "surface": ["legal_or_compliance_assertion", "people_impacting_decision"]
+  },
+  "skill_chain": {
+    "intake": {
+      "primary": [],
+      "optional": ["doc"],
+      "fallback": "Extract slide titles, notes, and visible text with available local tools.",
+      "handoff_artifact": "deck_inventory.md"
+    },
+    "produce": {
+      "primary": ["pyramid-principle:pyramid-presentation"],
+      "optional": ["research"],
+      "fallback": "Apply one-job-per-slide and answer-first storyline checks manually.",
+      "handoff_artifact": "audit_report.md"
+    },
+    "review": {
+      "primary": ["pyramid-principle:pyramid-audit"],
+      "optional": ["research"],
+      "fallback": "Run rubric.md validators against each slide finding.",
+      "handoff_artifact": "audit_verdict.md"
+    },
+    "learn": {
+      "primary": ["build-loop:knowledge"],
+      "optional": [],
+      "fallback": "Record recurring deck failure patterns in the report.",
+      "handoff_artifact": "deck_lessons.md"
+    }
+  },
+  "learn": {
+    "store": ["deck_failure_patterns", "reusable_slide_patterns", "source_quirks", "rubric_failures"]
+  }
+}

package/skills/loop-builder/presets/research-synthesis.yaml

@@ -0,0 +1,96 @@
+{
+  "id": "research-synthesis",
+  "title": "Research Synthesis Loop",
+  "summary": "Answer a question with explicit source strategy, evidence extraction, confidence, and durable citations.",
+  "inputs": [
+    "research question",
+    "decision use",
+    "freshness requirement",
+    "candidate sources",
+    "source quality rubric"
+  ],
+  "outputs": [
+    "source strategy",
+    "evidence table",
+    "synthesis memo",
+    "claim verification log",
+    "reusable search strategy"
+  ],
+  "phases": {
+    "assess": {
+      "goal": "Frame the question, scope, decision use, freshness need, and inclusion/exclusion rules.",
+      "required": ["question", "decision_use", "freshness_requirement", "inclusion_exclusion"]
+    },
+    "plan": {
+      "goal": "Plan source collection, extraction fields, and confidence markers.",
+      "required": ["source_strategy", "extraction_schema", "confidence_scheme"]
+    },
+    "produce": {
+      "goal": "Collect sources, extract evidence, and synthesize the answer.",
+      "required": ["source_list", "evidence_table", "synthesis"]
+    },
+    "review": {
+      "goal": "Verify claims, dates, statistics, and contested points.",
+      "required": ["claim_inventory", "verification_log", "weak_claims"]
+    },
+    "learn": {
+      "goal": "Persist the report, source quirks, and reusable search strategy.",
+      "required": ["saved_report", "search_strategy", "source_quirks"]
+    }
+  },
+  "validators": [
+    {
+      "id": "claim_citation",
+      "pass_condition": "Every material claim has a citation or is marked inferred/unsupported.",
+      "method": "review"
+    },
+    {
+      "id": "freshness_trace",
+      "pass_condition": "Time-sensitive claims include source publication or capture date.",
+      "method": "review"
+    },
+    {
+      "id": "source_quality",
+      "pass_condition": "Each source has a quality tier and role in the answer.",
+      "method": "review"
+    },
+    {
+      "id": "weak_claim_handling",
+      "pass_condition": "Unsupported claims are removed, downgraded, or labeled explicitly.",
+      "method": "review"
+    }
+  ],
+  "gates": {
+    "confirm": ["external_send", "legal_or_compliance_assertion", "sensitive_data_exposure"],
+    "surface": ["people_impacting_decision", "money_movement"]
+  },
+  "skill_chain": {
+    "intake": {
+      "primary": ["research"],
+      "optional": [],
+      "fallback": "Use local repo/wiki scan and explicit source list.",
+      "handoff_artifact": "research_packet.md"
+    },
+    "produce": {
+      "primary": ["research"],
+      "optional": ["pyramid-principle:pyramid-short-form"],
+      "fallback": "Draft synthesis from evidence table with confidence markers.",
+      "handoff_artifact": "synthesis_memo.md"
+    },
+    "review": {
+      "primary": ["research"],
+      "optional": [],
+      "fallback": "Run claim inventory and citation checks manually.",
+      "handoff_artifact": "claim_verification_log.md"
+    },
+    "learn": {
+      "primary": ["build-loop:knowledge"],
+      "optional": [],
+      "fallback": "Persist source quirks and search strategy in the report.",
+      "handoff_artifact": "research_lessons.md"
+    }
+  },
+  "learn": {
+    "store": ["search_strategy", "source_quirks", "claim_failures", "useful_sources"]
+  }
+}

package/skills/loop-builder/presets/source-ingestion-raw-data-audit.yaml

@@ -0,0 +1,96 @@
+{
+  "id": "source-ingestion-raw-data-audit",
+  "title": "Source Ingestion and Raw Data Audit Loop",
+  "summary": "Inventory, dedupe, preserve, and audit source artifacts before promoting claims or source cards.",
+  "inputs": [
+    "source folder",
+    "candidate files",
+    "spreadsheets or survey exports",
+    "artifact versions",
+    "project question"
+  ],
+  "outputs": [
+    "source inventory",
+    "duplicate and version map",
+    "raw-data manifest",
+    "ingestion priority list",
+    "source-card drafting queue"
+  ],
+  "phases": {
+    "assess": {
+      "goal": "Identify source roots, sensitive material, project questions, and raw-data-bearing files.",
+      "required": ["source_roots", "sensitivity_labels", "project_questions", "raw_data_candidates"]
+    },
+    "plan": {
+      "goal": "Prioritize ingestion by decision relevance, source quality, and dedupe risk.",
+      "required": ["ingestion_order", "duplicate_strategy", "raw_preservation_strategy"]
+    },
+    "produce": {
+      "goal": "Write inventory, duplicate map, raw-data manifest, and source-card queue.",
+      "required": ["hashes", "row_column_counts", "sheet_names", "filters_or_denominators"]
+    },
+    "review": {
+      "goal": "Verify version choices and that quantitative claims can trace to raw or surrogate data.",
+      "required": ["version_verdicts", "raw_trace_checks", "uncertain_items"]
+    },
+    "learn": {
+      "goal": "Capture source quirks and future ingestion rules.",
+      "required": ["source_quirks", "reusable_ingestion_rules"]
+    }
+  },
+  "validators": [
+    {
+      "id": "source_inventory_complete",
+      "pass_condition": "Every candidate source has path, type, size or count proxy, and ingestion status.",
+      "method": "code-or-review"
+    },
+    {
+      "id": "duplicate_resolution",
+      "pass_condition": "Same-title or same-hash files are grouped with an explicit keep/compare/defer verdict.",
+      "method": "review"
+    },
+    {
+      "id": "raw_data_trace",
+      "pass_condition": "Every quantitative source links to an original file or stable surrogate with sheet/table names and row/column counts.",
+      "method": "code-or-review"
+    },
+    {
+      "id": "uncertain_items_flagged",
+      "pass_condition": "Uncertain, inaccessible, or sensitive items are listed instead of silently skipped.",
+      "method": "review"
+    }
+  ],
+  "gates": {
+    "confirm": ["sensitive_data_exposure", "irreversible_source_change"],
+    "surface": ["legal_or_compliance_assertion"]
+  },
+  "skill_chain": {
+    "intake": {
+      "primary": ["research"],
+      "optional": ["doc"],
+      "fallback": "Run filesystem inventory and summarize file types manually.",
+      "handoff_artifact": "source_inventory.md"
+    },
+    "produce": {
+      "primary": [],
+      "optional": ["research"],
+      "fallback": "Use deterministic scripts or shell inventory for hashes and counts.",
+      "handoff_artifact": "raw_data_manifest.md"
+    },
+    "review": {
+      "primary": ["research"],
+      "optional": [],
+      "fallback": "Review duplicate/version choices against file metadata and source content.",
+      "handoff_artifact": "ingestion_review.md"
+    },
+    "learn": {
+      "primary": ["build-loop:knowledge"],
+      "optional": [],
+      "fallback": "Append durable ingestion lessons to the report.",
+      "handoff_artifact": "ingestion_lessons.md"
+    }
+  },
+  "learn": {
+    "store": ["source_quirks", "dedupe_rules", "raw_data_rules", "uncertain_item_patterns"]
+  }
+}

package/skills/loop-builder/references/spec-format.md

@@ -0,0 +1,80 @@
+# Loop Spec Format
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+A focused-loop spec is the domain contract for a reusable workflow. The runner owns phase movement, validation order, iteration, gates, queues, and learn/memory. The spec owns the artifact vocabulary.
+
+## Required Fields
+
+| Field | Purpose |
+|---|---|
+| `schema_version` | Loop spec version. Start at `1`. |
+| `id` | Kebab-case loop identifier. |
+| `title` | Human-readable loop name. |
+| `summary` | One-sentence purpose. |
+| `inputs` | Accepted source materials or state surfaces. |
+| `outputs` | Artifacts the loop produces. |
+| `phases` | Domain-specific work contract per phase. |
+| `validators` | Pass/fail checks used during review. |
+| `gates` | Human confirmation boundaries. |
+| `skill_chain` | Optional phase-to-skill routing plan. |
+| `learn` | Durable reuse payload. |
+
+## Skill Chain Shape
+
+`skill_chain` is a plan for chaining specialized skills. It is advisory unless the runner or host can prove the named skill exists.
+
+Each phase may declare:
+
+| Field | Purpose |
+|---|---|
+| `primary` | Preferred skills for this phase. |
+| `optional` | Skills to use when source type or scope warrants them. |
+| `fallback` | What to do if the skill is unavailable. |
+| `handoff_artifact` | Required output from the chained skill. |
+
+Example:
+
+```yaml
+skill_chain:
+  intake:
+    primary:
+      - research
+    optional:
+      - doc
+    fallback: "Manual source inventory with cited file paths."
+    handoff_artifact: "source_inventory.md"
+```
+
+## Gate Rules
+
+Keep common gates centralized. Loop specs should name examples, not redefine policy.
+
+Standard confirmation gates:
+
+- external_send
+- sensitive_data_exposure
+- money_movement
+- legal_or_compliance_assertion
+- production_or_customer_operation
+- people_impacting_decision
+- irreversible_source_change
+
+## Validator Rules
+
+Validators should be binary. Avoid vague scores. If the check requires judgment, phrase it as a pass/fail rubric with named evidence.
+
+Good:
+
+```yaml
+- id: source_trace
+  pass_condition: "Every material claim cites a source path, slide, row, transcript timestamp, or explicitly marked assumption."
+  method: "review"
+```
+
+Weak:
+
+```yaml
+- id: quality
+  pass_condition: "The artifact is good."
+```