Repository navigation
aiops: guidelines - Align workflow references and retention #419
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
890a63e
a345a0a
7a3bd9b
06d6f26
dfb69b4
a424b5c
37ee164
96e79eb
cec4305
939b18f
88e8a95
cfbab2d
09e6d88
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -20,8 +20,14 @@ documentation organized in separate files. | |||||
|
|
||||||
| ### 🤖 Default AI Workflow (MUST FOLLOW) | ||||||
|
|
||||||
| **When asked to write a prompt, audit, or review, ALWAYS follow this sequence:** | ||||||
|
|
||||||
| **See the [Workflow Orchestration Skill](../.claude/skills/workflow-orchestration/SKILL.md) for comprehensive guidance on:** | ||||||
| - Single-file audit workflows (4-step: prompt → audit → report → tasks) | ||||||
| - Multi-audit orchestrator workflows with parallel execution | ||||||
| - Folder structure and naming conventions | ||||||
| - YAML frontmatter templates for all content types | ||||||
| - Task list management and archiving procedures | ||||||
|
|
||||||
| **Quick reference:** When told to "write a prompt" or "audit X", use the skill's decision tree to choose single-file or orchestrator workflow, then execute the full sequence (create prompt → run audit → save report → extract tasks). The skill provides reusable YAML templates and detailed step-by-step guidance. | ||||||
| 1. **Create a prompt** in `/prompts/` — defines the audit scope, steps, and references to relevant guidelines. | ||||||
|
|
||||||
| 1. **Run the audit** described in the prompt against the codebase and guidelines. | ||||||
|
|
@@ -69,21 +75,23 @@ general documentation. | |||||
|
|
||||||
| ### 📁 Mandatory Folder Conventions | ||||||
|
|
||||||
| The project uses three dedicated workflow folders. **All AI-generated and human-authored workflow artifacts MUST be stored in these folders.** See the [Workflow Orchestration Skill](../.claude/skills/workflow-orchestration/SKILL.md) for full folder structure rules and conventions. | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: sed -n '45,82p' guidelines/Guidelines.md
rg -n -C 5 'Folder|folders|prompts|reports|tasks|docs|scripts' .claude/skills/workflow-orchestration/SKILL.mdRepository: lightspeedwp/ThisOneTimeOnAcidCom Length of output: 20859 Clarify the three workflow folders. The sentence names three workflow folders, but the table also lists Suggested fix-The project uses three dedicated workflow folders. **All AI-generated and human-authored workflow artifacts MUST be stored in these folders.** See the [Workflow Orchestration Skill](../.claude/skills/workflow-orchestration/SKILL.md) for full folder structure rules and conventions.
+The project uses three dedicated workflow folders: `/prompts/`, `/reports/`, and `/tasks/`. **All AI-generated and human-authored workflow artefacts MUST be stored in these folders.** Use `/docs/` for general project documentation and `/scripts/` for build, utility, and automation scripts. See the [Workflow Orchestration Skill](../.claude/skills/workflow-orchestration/SKILL.md) for full folder structure rules and conventions.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||
| The project uses three dedicated workflow folders. **All AI-generated and | ||||||
| human-authored workflow artifacts MUST be stored in these folders.** Never place | ||||||
| prompts, reports, or task lists anywhere else (e.g., never in root, never in | ||||||
| `/guidelines/`). | ||||||
|
|
||||||
| | Folder | Purpose | Naming Convention | | ||||||
| |---|---|---| | ||||||
| | `/prompts/` | All prompt files for AI-assisted tasks | `{topic}.md` or subfolder `{topic}/` with `orchestrator.md` | | ||||||
| | `/reports/` | All audit findings, analysis results, reports | Subfolder per audit: `/reports/{audit-name}/` | | ||||||
| | `/tasks/` | All task lists and checklists | `task-list.md` is the master general-purpose task list | | ||||||
| | `/docs/` | General project documentation, quick references, attributions | Descriptive filenames (e.g., `Attributions.md`, `quick-reference.md`) | | ||||||
| | `/scripts/` | All build, utility, and automation scripts (`.ts`, `.sh`, `.js`) | Descriptive filenames (e.g., `verify-build.ts`, `deploy.sh`) | | ||||||
| **Quick Reference:** | ||||||
|
|
||||||
| **Rules:** | ||||||
| | Folder | Purpose | | ||||||
| |---|---| | ||||||
| | `/prompts/` | All prompt files for AI-assisted tasks | | ||||||
| | `/reports/` | All audit findings, analysis results, reports | | ||||||
| | `/tasks/` | All task lists and checklists; `/tasks/task-list.md` is the persistent master | | ||||||
| | `/docs/` | General project documentation, quick references, attributions | | ||||||
| | `/scripts/` | All build, utility, and automation scripts | | ||||||
|
|
||||||
| **Critical rule:** Never delete `/tasks/task-list.md` — it is the persistent master checklist. | ||||||
| 1. **Prompts:** Always create new prompt files in `/prompts/`. For multi-step workflows, create a subfolder with a master `orchestrator.md` and child prompt files. | ||||||
|
|
||||||
| 1. **Reports:** Always write reports to `/reports/`, inside a suitable subfolder (e.g., `/reports/root-cleanup/`, `/reports/css-audit/`). One subfolder per audit or topic. | ||||||
|
|
@@ -166,6 +174,10 @@ created, completed, or archived. | |||||
|
|
||||||
| 1. When ALL tasks in a task list are marked complete, move the entry in `master-task-list.md` from "Active" to "Completed (pending archive)" | ||||||
|
|
||||||
| **Report archiving process:** | ||||||
| 1. When a report's associated task list is 100% complete, wait 30 days from completion, then move the report folder from `/reports/{topic}/` to `/reports/archived/{topic}/` | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: sed -n '116,134p' guidelines/Guidelines.md
rg -n -C 12 'archive|archiv|pending|blocker|finding|frontmatter|status' .claude/skills/workflow-orchestration/SKILL.mdRepository: lightspeedwp/ThisOneTimeOnAcidCom Length of output: 22837 Preserve the complete archive checklist. A 100% complete task list and a 30-day wait are not sufficient. Record Suggested documentation fix-1. When a report's associated task list is 100% complete, wait 30 days from completion, then move the report folder from `/reports/{topic}/` to `/reports/archived/{topic}/`
+1. When all tasks are complete, mark the task list and master-tracker entry as `Completed (pending archive)` and record the completion date. After 30 days, archive the report only when all findings are addressed or explicitly deferred, the report is finalised, no open questions or blockers remain, and every report's YAML frontmatter has `status: "archived"`. Then move the report folder from `/reports/{topic}/` to `/reports/archived/{topic}/`. See the [Workflow Orchestration Skill archive process](../.claude/skills/workflow-orchestration/SKILL.md#section-3-archiving-completed-work).📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||
| 2. Reports in `/reports/archived/` can be deleted after 7 days | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win Confirm the seven-day report deletion policy. The workflow skill permits deletion after 30 additional days for archived task-list files. It does not define a seven-day deletion period for archived report folders. Confirm the retention policy before documenting report deletion as permitted. 🤖 Prompt for AI Agents |
||||||
| 3. Only delete from `/reports/archived/` — never delete active reports | ||||||
|
Comment on lines
+177
to
+180
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win Remove the conflicting early-deletion instruction. Line 101 still says 🤖 Prompt for AI Agents |
||||||
| 1. After 30 days in "Completed", move the file to `/tasks/archived/` and update `master-task-list.md` | ||||||
|
|
||||||
| 1. Only delete from `/tasks/archived/` — never delete active or recently completed task lists | ||||||
|
|
||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -52,8 +52,7 @@ Follow this **exact reading order** to understand the design system: | |
| 1. **[design-tokens/spacing.md](./design-tokens/spacing.md)** - Spacing system | ||
|
|
||
| #### Step 4: Understand Data System (REQUIRED) | ||
|
|
||
| 1. **[Data System Documentation](../data/README.md)** - Mock data system and centralized content management | ||
| 15. **[Data System Documentation](./data-models.md)** - Data model definitions and centralized content management | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win Obtain owner approval before merging this protected-file change. The 🤖 Prompt for AI AgentsSources: Coding guidelines, Pipeline failures |
||
|
|
||
| #### Step 5: Read Theme Documentation (REQUIRED) | ||
|
|
||
|
|
@@ -200,7 +199,7 @@ guidelines/ | |
| ## Building a Page Component | ||
|
|
||
| - Start with [overview-components.md](./overview-components.md) | ||
| - Check [Data System Documentation](../data/README.md) for content | ||
| - Check [data-models.md](./data-models.md) for content structure | ||
| - Review [Guidelines.md](./Guidelines.md) Section 1 for architecture | ||
|
|
||
| ## Using a Specific Component | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Obtain approval before modifying this protected file.
guidelines/is protected and the Protected Files Guard has failed. Open the required[PROTECTED-FILE-CHANGE-REQUEST]issue and obtain explicit owner approval, or revert this file, before merge.As per coding guidelines, protected files require explicit approval.
🤖 Prompt for AI Agents
Sources: Coding guidelines, Pipeline failures