docs(workflow): add task creation documentation to workflow by NTCoding · Pull Request #108 · NTCoding/living-architecture

NTCoding · 2026-01-10T10:40:28Z

User description

Summary

Add comprehensive task creation documentation to workflow
Document two types of tasks: PRD tasks and tech improvement tasks
Add create-tech-improvement-task.sh script for non-PRD tasks
Clarify mandatory use of scripts vs direct gh/git commands

Test plan

Documentation accurately reflects task creation process
Script examples are correct and tested
All workflow steps documented with proper permissions

🤖 Generated with Claude Code

PR Type

Documentation

Description

Add comprehensive task creation documentation with mandatory script usage
Document two task types: PRD tasks and tech improvement tasks
Include command syntax and parameter descriptions for both scripts
Add debugging patterns and workflow corrections from recent learnings

Diagram Walkthrough

flowchart LR
  TaskCreation["Task Creation Section"]
  PRDTasks["PRD Tasks<br/>create-task.sh"]
  TechTasks["Tech Improvement Tasks<br/>create-tech-improvement-task.sh"]
  Commands["Command Syntax<br/>& Parameters"]
  TaskCreation --> PRDTasks
  TaskCreation --> TechTasks
  PRDTasks --> Commands
  TechTasks --> Commands

File Walkthrough

Relevant files

Documentation

task-workflow.md `Add task creation documentation and workflow patterns` docs/workflow/task-workflow.md Add new "Task Creation" section with mandatory script usage policy Document PRD tasks using `create-task.sh` with milestone linking Document tech improvement tasks using `create-tech-improvement-task.sh` Include complete command syntax and parameter descriptions for both task types Add debugging patterns, VitePress routing gotchas, and post-merge workflow corrections	+43/-0

Summary by CodeRabbit

Documentation
- Added Task Creation section to Task Workflow documentation, covering procedures for creating PRD Tasks and Tech Improvement Tasks with command examples, required parameters, body sections, and acceptance criteria guidelines for each task type.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

- Add Chrome MCP tools guidance to CLAUDE.md for browser debugging - Add VitePress routing gotcha to apps/docs/CLAUDE.md - Add jsdom testing limitations to testing.md - Update task-workflow.md: never reuse squash-merged branches Co-Authored-By: Claude Opus 4.5 <[email protected]>

Correct order: reflect first (needs review files), create issues, cleanup worktree, then implement via normal task workflow. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Add Task Creation section documenting two types of tasks: - PRD tasks using create-task.sh (milestone-linked) - Tech improvement tasks using create-tech-improvement-task.sh (no milestone) Mandate using approved scripts only, never gh issue create directly. Co-Authored-By: Claude Haiku 4.5 <[email protected]>

…n-workflow-docs

coderabbitai · 2026-01-10T10:40:36Z

📝 Walkthrough

Walkthrough

A new "Task Creation" section is added to task-workflow documentation, mandating the use of approved scripts for task creation. The documentation distinguishes between PRD Tasks and Tech Improvement Tasks, detailing their respective scripts, use cases, linking semantics, command examples, and required parameters including body sections and acceptance criteria.

Changes

Cohort / File(s)	Summary
Task Creation Documentation `docs/workflow/task-workflow.md`	Added new "Task Creation" section under Task Workflow lifecycle with command examples for PRD Tasks and Tech Improvement Tasks, parameter definitions, required body sections, and acceptance criteria format.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

feat(workflow): add review workflow helper scripts #92 — Documents and mandates using workflow helper scripts for task creation, while this PR adds the exact helper scripts that the main PR documents
chore: workflow script encapsulation #24 — Modifies the task-creation workflow by introducing/mandating scripted task creation and accompanying documentation and scripts
feat(scripts): add git worktree support to task workflow #72 — Modifies task-workflow.md and the retrieved PR adds/changes scripts that directly implement the task-creation and cleanup commands this PR documents

Suggested labels

Review effort 2/5

Poem

🐰 Task creation flows so true,
Scripts and docs in perfect view,
PRD and tech, two paths now bright,
With words so clear, the future's right!
✨

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(workflow): add task creation documentation to workflow' accurately and specifically summarizes the main change—adding documentation about task creation to the workflow documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

qodo-code-review · 2026-01-10T10:40:46Z

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

cloudflare-workers-and-pages · 2026-01-10T10:40:59Z

Deploying living-architecture with Cloudflare Pages

Latest commit:	`f478966`
Status:	✅ Deploy successful!
Preview URL:	https://6878b672.living-architecture.pages.dev
Branch Preview URL:	https://docs-add-task-creation-workf.living-architecture.pages.dev

View logs

qodo-code-review · 2026-01-10T10:41:35Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Unify task creation into one script Merge the two separate scripts for creating PRD tasks and tech improvement tasks into a single, unified script. This can be achieved by making the milestone parameter optional to differentiate between task types. Examples: docs/workflow/task-workflow.md [41-69] ### Two Types of Tasks 1. PRD Tasks — Milestone-driven work from Product Requirements Documents - Use: `./scripts/create-task.sh` - When: Breaking down PRD deliverables into implementable tasks - Links to: Milestone, PRD sections, functional requirements 2. Tech Improvement Tasks — Quality, debt, bugs, improvements - Use: `./scripts/create-tech-improvement-task.sh` - When: Fixes, refactoring, tech debt, performance, tests ... (clipped 19 lines) Solution Walkthrough: Before: # Documentation describes two separate scripts for task creation # 1. For PRD Tasks # ./scripts/create-task.sh <milestone> <title> <body> # ... # 2. For Tech Improvement Tasks # ./scripts/create-tech-improvement-task.sh \ # <title> \ # <references> \ # <summary> \ # ... After: # Documentation describes a single, unified script # ./scripts/create-task.sh handles both cases # For example, using an optional milestone or a type flag # PRD Task # ./scripts/create-task.sh --type prd --milestone <milestone> ... # Tech Improvement Task # ./scripts/create-task.sh --type tech-improvement --title <title> ... Suggestion importance[1-10]: 8 __ Why: This is a significant design suggestion that correctly identifies an opportunity to simplify the documented workflow by unifying two separate scripts, reducing complexity and maintenance overhead.	Medium
General	Quote script arguments Add quotes around the `<title>` and arguments in the `create-task.sh` command example to handle spaces correctly. docs/workflow/task-workflow.md [57] -./scripts/create-task.sh <milestone> <title> <body> +./scripts/create-task.sh <milestone> "<title>" "<body>" Apply / Chat Suggestion importance[1-10]: 7 __ Why: This is a valid and important correction. Without quotes, the documented script command will fail for any title or body containing spaces, which is a very common use case. This significantly improves the documentation's accuracy and usability.	Medium
More

sonarqubecloud · 2026-01-10T10:41:41Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @docs/workflow/task-workflow.md:
- Around line 37-78: The PRD task docs state "Body must contain all 10 sections"
but never lists them; update the "PRD Task" section to either enumerate the ten
required sections (copying the exact headings/order used by the /create-tasks
skill) or remove that mandate if the project intends enforcement solely in the
skill. Specifically, edit the PRD Task paragraph near the "Body must contain all
10 sections" note to add a new subsection that lists the ten section headings
and a one-line description for each (so users running ./scripts/create-task.sh
know the required structure), and ensure the mention either links to that new
subsection or is removed/changed to "see /create-tasks skill" if you opt not to
document them inline.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 10a73d4 and f478966.

📒 Files selected for processing (1)

docs/workflow/task-workflow.md

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T10:14:57.499Z
Learning: Follow the task workflow defined in `docs/workflow/task-workflow.md` from start to finish for all tasks; do not make changes or commit code without following these steps

📚 Learning: 2026-01-10T10:14:57.499Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T10:14:57.499Z
Learning: Follow the task workflow defined in `docs/workflow/task-workflow.md` from start to finish for all tasks; do not make changes or commit code without following these steps

Applied to files:

docs/workflow/task-workflow.md

📚 Learning: 2026-01-10T10:14:57.499Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T10:14:57.499Z
Learning: Use scripts in `./scripts/` for git and GitHub operations (PRs, issues, tasks); do not use `gh` or `git` commands directly unless no script exists

Applied to files:

docs/workflow/task-workflow.md

🔇 Additional comments (2)

docs/workflow/task-workflow.md (2)
71-76: Good parameter documentation for tech improvement tasks.

The parameter definitions for create-tech-improvement-task.sh are clear and explicit. The descriptions help users understand what content is expected in each parameter.

37-39: Clarify or link the /create-tasks reference at line 59.

The reference to /create-tasks skill documentation exists in ./.claude/commands/create-tasks.md and documents the 10 required sections. However, for clarity to developers reading this file, consider:

Adding the file path directly: ./.claude/commands/create-tasks.md

Or providing a one-sentence clarification that /create-tasks refers to the Claude command documentation in the .claude/commands/ directory

This improves accessibility without requiring readers to infer the reference location from the command syntax alone.
⛔ Skipped due to learnings
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T10:14:57.499Z
Learning: Use scripts in `./scripts/` for git and GitHub operations (PRs, issues, tasks); do not use `gh` or `git` commands directly unless no script exists
Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T10:14:57.499Z
Learning: Follow the task workflow defined in `docs/workflow/task-workflow.md` from start to finish for all tasks; do not make changes or commit code without following these steps

NTCoding and others added 4 commits January 10, 2026 09:57

docs: fix post-merge reflection process

a245d9a

Correct order: reflect first (needs review files), create issues, cleanup worktree, then implement via normal task workflow. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Merge remote-tracking branch 'origin/main' into docs/add-task-creatio…

f478966

…n-workflow-docs

qodo-code-review Bot added the Review effort 1/5 label Jan 10, 2026

coderabbitai Bot requested changes Jan 10, 2026

View reviewed changes

Comment thread docs/workflow/task-workflow.md

coderabbitai Bot approved these changes Jan 10, 2026

View reviewed changes

NTCoding merged commit c046fa3 into main Jan 10, 2026
18 checks passed

This was referenced Jan 10, 2026

docs: update task workflow with non-milestone task listing #115

Merged

docs: investigate parallel workflow design #120

Closed

coderabbitai Bot mentioned this pull request Jan 31, 2026

docs(prd): define Phase 12-14 PRDs for connection detection and workflows #183

Merged

3 tasks

Navigation Menu

Repository navigation

docs(workflow): add task creation documentation to workflow - #108

docs(workflow): add task creation documentation to workflow#108
NTCoding merged 4 commits into
mainfrom
docs/add-task-creation-workflow-docs

NTCoding commented Jan 10, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jan 10, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

Uh oh!

qodo-code-review Bot commented Jan 10, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Jan 10, 2026 •

edited

Loading

Uh oh!

qodo-code-review Bot commented Jan 10, 2026

Examples:

Solution Walkthrough:

Before:

After:

Uh oh!

sonarqubecloud Bot commented Jan 10, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

NTCoding commented Jan 10, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

Summary

Test plan

PR Type

Description

Diagram Walkthrough

File Walkthrough

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

Uh oh!

qodo-code-review Bot commented Jan 10, 2026

PR Compliance Guide 🔍

Uh oh!

cloudflare-workers-and-pages Bot commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying living-architecture with Cloudflare Pages

Uh oh!

qodo-code-review Bot commented Jan 10, 2026

PR Code Suggestions ✨

Examples:

Solution Walkthrough:

Before:

After:

Uh oh!

sonarqubecloud Bot commented Jan 10, 2026

Quality Gate passed

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

NTCoding commented Jan 10, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jan 10, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jan 10, 2026 •

edited

Loading