From 5c72544eca4a4ffc8e4da53b17774f268f417f0b Mon Sep 17 00:00:00 2001 From: Tyler Gillispie Date: Tue, 25 Aug 2026 12:20:31 -0700 Subject: [PATCH] docs(tasks): establish plan.md, debug.md and streamline path.md master index --- tasks/debug.md | 52 +++++++++++++++++ tasks/path.md | 152 ++++++++----------------------------------------- tasks/plan.md | 51 +++++++++++++++++ 3 files changed, 128 insertions(+), 127 deletions(-) create mode 100644 tasks/debug.md create mode 100644 tasks/plan.md diff --git a/tasks/debug.md b/tasks/debug.md new file mode 100644 index 0000000..60e60de --- /dev/null +++ b/tasks/debug.md @@ -0,0 +1,52 @@ +# Root-Cause & System Investigation Protocol (`tasks/debug.md`) + +This protocol defines the standard for deeply investigating bugs, race +conditions, edge cases, or performance anomalies across local and production +environments without touching production code. + +--- + +## 1. Direct Execution Protocol (When You Are Investigating a Bug) + +When commanded to **"tasks/debug `[SYMPTOMS / ERROR]`"**: + +1. **Strict Read-Only Production Rule:** Experiment, research, and report ONLY. + Never modify production source files during an investigation. +2. **Hermetic Reproduction in `scratch/`:** + - Create minimal, standalone reproduction scripts or test harnesses in + `scratch/`. + - Trace data flows across network ingress, caching tiers (Valkey), database + (Postgres), and client runtimes. +3. **Formulate & Test Falsifiable Hypotheses:** Document what was tested, what + was disproven, and what was definitively verified. +4. **Deliverable Report:** Output a structured report in + `scratch/INVESTIGATIVE_REPORT.md` detailing: + - Verified Root Cause + - Discarded Hypotheses & Evidence + - Ranked Architectural Remediation Options (with trade-offs) + +--- + +## 2. Dispatch Template (When Preparing a Debug Prompt for Jules or External Agents) + +When commanded to **"tasks/debug a prompt for Jules on `[BUG / ISSUE]`"**, fill +in and provide the following block: + +```text +**Role:** Act as a Principal Systems & Security Investigator. + +**The Scope:** [Describe anomaly, bug symptoms, error logs, and affected components.] + +**Directives:** +- **STRICT CONSTRAINT:** Experiment, research, and report ONLY. Do not modify existing production code or create PRs with production changes. +- Place all reproduction test scripts and experiments in `scratch/` or hermetic test harnesses. + +**Your Task:** +1. Formulate clear, falsifiable hypotheses based on observed logs and symptoms. +2. Design and execute minimal reproduction scripts or benchmarks in `scratch/` to test each hypothesis in isolation. +3. Trace data flows through database, caching layers, ingress proxies, and client runtime engines. +4. Document the definitive root cause and rank potential architectural solutions from most reliable to least, with explicit rationale and trade-offs. + +**Deliverable:** +Author an investigative report in `scratch/INVESTIGATIVE_REPORT.md` detailing verified findings, discarded hypotheses, and ranked solutions. +``` diff --git a/tasks/path.md b/tasks/path.md index f1cc4b5..940628d 100644 --- a/tasks/path.md +++ b/tasks/path.md @@ -1,142 +1,40 @@ -**Intent of this file:** This file is intended for new-task-prompt development -and orchestrator templates. It is NOT for actual task research and creation. If -your current job is to create, plan, or format a task file, please refer to -`tasks/GUIDELINES.md` and ignore the templates in this file. +# Task Orchestration Protocols (`tasks/path.md`) + +This index maps out the standardized engineering workflow and action protocols +in the `tasks/` directory. --- -# Orchestrator Meta-Prompts (`tasks/path.md`) +## 🔄 The 4-Step Engineering Lifecycle -## 1. Task Planning Template (System Analyst) +The standard task pipeline follows a strict, sequential 4-step lifecycle: -_Use this template to instruct an agent (such as Jules) to take a technical -idea, critically analyze the existing codebase, identify risks/alternatives, and -draft a compliant task file in `tasks/new/`._ - -```text -**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/. - -**The Objective:** [State exactly what you want to achieve.] - -**Suggestions & Initial Thoughts:** -*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* -* [Suggestion 1] -* [Suggestion 2] - -**Your Task:** -1. Research the codebase and analyze this objective against our current architecture. -2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach? -3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. -4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. ``` +[1. plan] ──► [2. audit-1] ──► [3. do] ──► [4. audit-2] +``` + +| Step | Protocol File | Role | Purpose | Direct Command | Prompt Prep Command | +| :---: | :--------------------------------- | :------------- | :--------------------------------------------- | :------------------------ | :--------------------------------- | +| **1** | [`tasks/plan.md`](./plan.md) | System Analyst | Research codebase & draft task in `tasks/new/` | _"tasks/plan XYZ"_ | _"tasks/plan a prompt for Jules"_ | +| **2** | [`tasks/audit-1.md`](./audit-1.md) | Plan Critic | Audit, grade, and refine task plan | _"tasks/audit-1 task #1"_ | _"tasks/audit-1 prompt for Jules"_ | +| **3** | [`tasks/do.md`](./do.md) | Developer | Execute task, run gates, move to `complete/` | _"tasks/do task #1"_ | _"tasks/do a prompt for Jules"_ | +| **4** | [`tasks/audit-2.md`](./audit-2.md) | QA Auditor | Audit code quality & verify zero regressions | _"tasks/audit-2 branch"_ | _"tasks/audit-2 prompt for Jules"_ | --- -## 2. Implementation Execution Template (`tasks/do.md`) +## 🔬 Standalone / On-Demand Protocol -_Use this template when ready to command an agent to execute the work outlined -in an existing task file. See complete protocol in -[`tasks/do.md`](file:///home/tylerg/p/data/auth-yes/tasks/do.md)._ +Use this protocol out-of-band at any time to diagnose complex bugs or anomalies +without modifying production code. -```text -**Role:** Act as an Implementation Engineer. - -**The Task:** Please review and execute the plan detailed in `[tasks/new/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md]`. - -**Directives:** -1. Follow the strict 4-step state machine (Research -> Implementation -> Quality Gates -> Review). -2. Move the task file from `tasks/new/` to `tasks/wip/` before starting, and to `tasks/complete/` upon verification. -3. Apply minimal, pure functional modifications. -4. Ensure all downstream pipeline steps and context contracts remain intact. -5. Run all quality gates (`deno fmt`, `deno task lint`, `deno task check`, `deno task test`). -6. Run ONLY unit tests (`deno task test` / `deno test --allow-all`). Do NOT execute `deno task start` or `deno task dev` (live database daemons are not running in sandbox containers). -7. Upon successful completion and verification, update the task status according to `tasks/GUIDELINES.md`. -``` +| Protocol File | Role | Purpose | Direct Command | Prompt Prep Command | +| :----------------------------- | :----------- | :---------------------------------------------- | :-------------------- | :--------------------------------- | +| [`tasks/debug.md`](./debug.md) | Investigator | Root-cause analysis & experiments in `scratch/` | _"tasks/debug issue"_ | _"tasks/debug a prompt for Jules"_ | --- -## 3. Implementation & Code Quality Audit Template (`tasks/audit-2.md`) +## 📋 Task File Formatting & Naming Rules -_Use this template to perform an exhaustive post-implementation audit on code -changes, PR branches, or completed tasks before merging or deploying. See -complete protocol in -[`tasks/audit-2.md`](file:///home/tylerg/p/data/auth-yes/tasks/audit-2.md)._ - -```text -**Role:** Act as a Senior Security, Architecture & Quality Assurance Auditor. Do not modify production code or push commits during this audit session. Your sole deliverable is an objective Code Quality & Security Audit Report. - -**The Scope:** [Specify target branch, recent commits, modified files, or completed task in `tasks/wip/TASK_FILENAME.md`]. - -**Your Task:** -Audit the actual codebase changes against the original task specification and our system guidelines (`AGENTS.md`, `docs/`) using the 5-point implementation rubric in `tasks/audit-2.md`: -1. Specification & Scope Fidelity -2. Zero-Trust Security & Boundary Safety -3. Modularity & Clean Architecture -4. Quality Gates & Test Evidence -5. Runtime & Client-Side Integrity - -**Deliverable:** -Provide a structured code audit report with: -- **Overall Implementation Score:** [e.g. 5/5, 4/5, or Letter Grade] -- **Verdict:** [MERGE READY / REVISION REQUIRED / BLOCKED] -- **Successes & Verified Achievements:** Exact functionality verified and working as expected. -- **Deficiencies, Regressions & Failure Risks:** Technical bugs, unhandled errors, UX regressions, or security gaps found. -- **Actionable Remediation Suggestions:** Specific, prioritized code fixes or refactoring steps needed before final approval. -``` - ---- - -## 4. Task Plan Review & Critique Template (`tasks/audit-1.md`) - -_Use this template to critically audit, score, and refine new task files in -`tasks/new/` before approving them for implementation. See complete protocol in -[`tasks/audit-1.md`](file:///home/tylerg/p/data/auth-yes/tasks/audit-1.md)._ - -```text -**Role:** Act as a Principal Systems Architect and Task Quality Critic. Do not modify the codebase or execute code during this session. Your sole deliverable is a structured task critique report. - -**The Scope:** Review the newly generated task file in `[tasks/new/TASK_FILENAME.md]` against our master architectural guidelines (`AGENTS.md`, `docs/`, `tasks/GUIDELINES.md`). - -**Your Task:** -Critically evaluate the proposed task plan against the 5-point quality rubric in `tasks/audit-1.md`: -1. Metadata & Standards Compliance -2. Architectural Alignment & Safety -3. Purity & Simplicity (Avoiding bloat) -4. Implementation Precision & State Machine -5. Testing & Quality Gate Rigor - -**Deliverable:** -Provide a structured critique report with: -- **Overall Score / Rating:** [e.g. 5/5, 4/5, or Letter Grade] -- **Verdict:** [APPROVED / NEEDS REVISION / REJECTED] -- **Strengths & Plan Alignment:** Key architectural insights captured in the plan. -- **Identified Gaps & Potential Risks:** Missing edge cases, unaddressed failure modes, or UX/architectural oversights. -- **Concrete Suggested Revisions:** Exact adjustments, additions, or rewordings to incorporate into the task file before implementation starts. -``` - ---- - -## 5. Architecture & Root-Cause Investigation Template (Investigator) - -_Use this template to instruct an agent to deeply investigate complex bugs, -reproduction anomalies, or distributed edge cases without modifying production -code._ - -```text -**Role:** Act as a Principal Systems & Security Investigator. - -**The Scope:** [Describe anomaly, bug symptoms, error logs, and affected components.] - -**Directives:** -- **STRICT CONSTRAINT:** Experiment, research, and report ONLY. Do not modify existing production code or create PRs with production changes. -- Place all reproduction test scripts and experiments in `scratch/` or hermetic test harnesses. - -**Your Task:** -1. Formulate clear, falsifiable hypotheses based on observed logs and symptoms. -2. Design and execute minimal reproduction scripts or benchmarks to test each hypothesis in isolation. -3. Trace data flows through database, caching layers, ingress proxies, and client runtime engines. -4. Document the definitive root cause and rank potential architectural solutions from most reliable to least, with explicit rationale and trade-offs. - -**Deliverable:** -Author an investigative report in `scratch/INVESTIGATIVE_REPORT.md` detailing verified findings, discarded hypotheses, and ranked solutions. -``` +For exact task file naming conventions, sequence numbering, and +`# TASK METADATA` header requirements, refer to +[`tasks/GUIDELINES.md`](./GUIDELINES.md). diff --git a/tasks/plan.md b/tasks/plan.md new file mode 100644 index 0000000..4443e22 --- /dev/null +++ b/tasks/plan.md @@ -0,0 +1,51 @@ +# Task Planning & Specification Protocol (`tasks/plan.md`) + +This protocol defines the standard for researching and drafting new task +specifications in `tasks/new/` across greenfield repositories and mature, +existing codebases. + +--- + +## 1. Direct Execution Protocol (When You Are Planning a Task) + +When commanded to **"tasks/plan `[OBJECTIVE]`"**: + +1. **Remain Strictly Read-Only:** Do not modify any production source code + during planning. +2. **Deep Codebase Exploration:** + - For existing codebases: Inspect architecture, dependencies, data schemas, + and prior patterns (`AGENTS.md`, `docs/`, `server/`, `ui/`). + - Identify potential failure modes, circular import risks, and monolithic + file sprawl. +3. **Draft the Task Specification:** + - Create a new file in + `tasks/new/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md`. + - Adhere strictly to the `# TASK METADATA` header, Target Files list, + Architectural Risks, and Phased Implementation plan required by + `tasks/GUIDELINES.md`. +4. **Halt for Audit-1:** Stop after saving the task file in `tasks/new/` and + await task plan review (`tasks/audit-1.md`). + +--- + +## 2. Dispatch Template (When Preparing a Planning Prompt for Jules or External Agents) + +When commanded to **"tasks/plan a prompt for Jules on `[OBJECTIVE]`"**, fill in +and provide the following block: + +```text +**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify production files during this session. Your sole deliverable is to generate a compliant task file in tasks/new/. + +**The Objective:** [State exactly what you want to achieve.] + +**Suggestions & Initial Thoughts:** +*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* +* [Suggestion 1] +* [Suggestion 2] + +**Your Task:** +1. Research the codebase and analyze this objective against our current architecture and existing codebase patterns. +2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more modular, or more native approach? +3. Map out `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. +4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. +```