tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(tasks): establish plan.md, debug.md and streamline path.md master index

Browse Source
This commit is contained in:
Tyler Gillispie 2026-08-25 12:20:31 -07:00
parent d0a1492f6c
commit 5c72544eca
3 changed files with 128 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
tasks/debug.md Normal file
View File

@ -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.
```

152
tasks/path.md
View File

@ -1,142 +1,40 @@
**Intent of this file:** This file is intended for new-task-prompt development # Task Orchestration Protocols (`tasks/path.md`)
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 This index maps out the standardized engineering workflow and action protocols
`tasks/GUIDELINES.md` and ignore the templates in this file. 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 Use this protocol out-of-band at any time to diagnose complex bugs or anomalies
in an existing task file. See complete protocol in without modifying production code.
[`tasks/do.md`](file:///home/tylerg/p/data/auth-yes/tasks/do.md)._
```text | Protocol File | Role | Purpose | Direct Command | Prompt Prep Command |
**Role:** Act as an Implementation Engineer. | :----------------------------- | :----------- | :---------------------------------------------- | :-------------------- | :--------------------------------- |
| [`tasks/debug.md`](./debug.md) | Investigator | Root-cause analysis & experiments in `scratch/` | _"tasks/debug issue"_ | _"tasks/debug a prompt for Jules"_ |
**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`.
```
--- ---
## 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 For exact task file naming conventions, sequence numbering, and
changes, PR branches, or completed tasks before merging or deploying. See `# TASK METADATA` header requirements, refer to
complete protocol in [`tasks/GUIDELINES.md`](./GUIDELINES.md).
[`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.
```

51
tasks/plan.md Normal file
View File

@ -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`.
```