chore: update documentation and improve clarity across various files

Author: olivomarco

.agents/skills/humanizer/README.md

@@ -148,33 +148,10 @@ The skill also includes a final "obviously AI generated" audit pass and a second
 | 24 | **Excessive hedging** | "could potentially possibly" | "may" |
 | 25 | **Generic conclusions** | "The future looks bright" | Specific plans or facts |
 
-## Full Example
-
-**Before (AI-sounding):**
-> Great question! Here is an essay on this topic. I hope this helps!
->
-> AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
->
-> At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not just about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.
->
-> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge. Additionally, the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.
->
-> - 💡 **Speed:** Code generation is significantly faster, reducing friction and empowering developers.
-> - 🚀 **Quality:** Output quality has been enhanced through improved training, contributing to higher standards.
-> - ✅ **Adoption:** Usage continues to grow, reflecting broader industry trends.
->
-> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. In order to fully realize this potential, teams must align with best practices.
->
-> In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you’d like me to expand on any section!
-
-**After (Humanized):**
-> AI coding assistants can speed up the boring parts of the job. They're great at boilerplate: config files and the little glue code you don't want to write. They can also help you sketch a test, but you still have to read it.
->
-> The dangerous part is how confident the suggestions look. I've accepted code that compiled and passed lint, then discovered later it missed the point because I stopped paying attention.
->
-> If you treat it like autocomplete and review every line, it's useful. If you use it to avoid thinking, it will help you ship bugs faster.
->
-> The only real backstop is tests. Without them, you're mostly judging vibes.
+## Worked example
+
+The README keeps the pattern summary for quick reference. `SKILL.md` contains the
+canonical guidance and worked examples the editor follows.
 
 ## References
 
@@ -183,6 +160,7 @@ The skill also includes a final "obviously AI generated" audit pass and a second
 
 ## Version History
 
+- **2.8.1** - Reduced README duplication; `SKILL.md` remains the canonical source for worked examples.
 - **2.8.0** - Added style/cadence patterns #31-33 for manufactured punchlines, aphorism formulas, and conversational rhetorical openers; expanded #20 to catch offer-to-continue chatbot closers. 33 patterns total.
 - **2.7.0** - Added pattern #30 (diff-anchored writing); made em/en dashes a hard cut rather than "overuse"; expanded #21 to cover speculative gap-filling ("maintains a low profile"). 30 patterns total.
 - **2.6.0** - Cleanup pass: consolidated the duplicated workflow sections, gated the personality guidance to content where voice is wanted, removed the model-fingerprinting subsection, and condensed the worked example. No change to the 29 patterns.

.agents/skills/humanizer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: humanizer
-version: 2.8.0
+version: 2.8.1
 description: |
   Remove signs of AI-generated writing from text. Use when editing or reviewing
   text to make it sound more natural and human-written. Based on Wikipedia's

.github/workflows/ci-doctor.md

@@ -1,9 +1,8 @@
 ---
 description: |
-  This workflow is an automated CI failure investigator that triggers when monitored workflows fail.
-  Performs deep analysis of GitHub Actions workflow failures to identify root causes,
-  patterns, and provide actionable remediation steps. Analyzes logs, error messages,
-  and workflow configuration to help diagnose and resolve CI issues efficiently.
+  This workflow investigates failures in Daily Perf Improver and Daily Test Coverage
+  Improver. It analyzes their logs and configuration, then records actionable
+  remediation when the evidence supports it.
 
 on:
   workflow_run:
@@ -38,7 +37,7 @@ timeout-minutes: 10
 
 # CI Failure Doctor
 
-You are the CI Failure Doctor, an expert investigative agent that analyzes failed GitHub Actions workflows to identify root causes and patterns. Your goal is to conduct a deep investigation when the CI workflow fails.
+You are the CI Failure Doctor. Investigate failures in the two monitored workflows, identify the supported cause, and record actionable remediation.
 
 ## Current Context
 
@@ -55,7 +54,7 @@ You are the CI Failure Doctor, an expert investigative agent that analyzes faile
 ### Phase 1: Initial Triage
 
 1. **Verify Failure**: Check that `${{ github.event.workflow_run.conclusion }}` is `failure` or `cancelled`
-2. **Deduplication Check**: Read `/tmp/memory/investigations/analyzed-runs.json` from the cache. If the current run ID (`${{ github.event.workflow_run.id }}`) is already listed, **stop immediately** — this run has already been investigated. After completing a new investigation, append the run ID to this index to prevent re-analysis.
+2. **Deduplication Check**: If the cache restored `/tmp/memory/investigations/analyzed-runs.json`, read it. If the current run ID (`${{ github.event.workflow_run.id }}`) is already listed, **stop immediately** — this run has already been investigated. After completing a new investigation, append the run ID so it can be restored by a later run.
 3. **Get Workflow Details**: Use `get_workflow_run` to get full details of the failed run
 4. **List Jobs**: Use `list_workflow_jobs` to identify which specific jobs failed
 5. **Quick Assessment**: Determine if this is a new type of failure or a recurring pattern
@@ -79,8 +78,7 @@ You are the CI Failure Doctor, an expert investigative agent that analyzes faile
 
 ### Phase 3: Historical Context Analysis  
 
-1. **Search Investigation History**: Use file-based storage to search for similar failures:
-   - Read from cached investigation files in `/tmp/memory/investigations/`
+1. **Search Investigation History**: If the cache restored prior investigation files, search `/tmp/memory/investigations/` for similar failures:
    - Parse previous failure patterns and solutions
    - Look for recurring error signatures
 2. **Issue History**: Search existing issues for related problems
@@ -105,7 +103,7 @@ You are the CI Failure Doctor, an expert investigative agent that analyzes faile
 
 ### Phase 5: Pattern Storage and Knowledge Building
 
-1. **Store Investigation**: Save structured investigation data to files:
+1. **Store Investigation**: Save structured investigation data for cache capture:
    - Write investigation report to `/tmp/memory/investigations/<timestamp>-<run-id>.json`
    - Store error patterns in `/tmp/memory/patterns/`
    - Maintain an index file of all investigations for fast searching
@@ -192,8 +190,8 @@ When creating an investigation issue, use this structure:
 
 ## Cache Usage Strategy
 
-- Store investigation database and knowledge patterns in `/tmp/memory/investigations/` and `/tmp/memory/patterns/`
+- Use `/tmp/memory/investigations/` and `/tmp/memory/patterns/` as cache-backed working storage; do not assume they exist unless the cache restores them.
 - Cache detailed log analysis and artifacts in `/tmp/investigation/logs/` and `/tmp/investigation/reports/`
-- Persist findings across workflow runs using GitHub Actions cache
+- Make findings available to later runs through the configured GitHub Actions cache
 - Build cumulative knowledge about failure patterns and solutions using structured JSON files
 - Use file-based indexing for fast pattern matching and similarity detection

.github/workflows/issue-triage-agent.md

@@ -30,7 +30,7 @@ imports:
 
 # Issue Triage Agent
 
-List open issues in ${{ github.repository }} that have no labels. For each unlabeled issue, analyze the title and body, then add one of the allowed labels: `bug`, `feature`, `enhancement`, `documentation`, `question`, `help-wanted`, or `good-first-issue`, `community`.
+List open issues in ${{ github.repository }} that have no labels. For each unlabeled issue, analyze the title and body, then add one allowed label: `bug`, `feature`, `enhancement`, `documentation`, `question`, `help-wanted`, or `good-first-issue`.
 
 Skip issues that:
 - Already have any of these labels
@@ -87,5 +87,4 @@ This provides both per-issue context and batch visibility.
 - `documentation`: Pertains to issues related to documentation, such as missing or unclear docs.
 - `question`: Used for issues that are asking for clarification or have questions about the project.
 - `help-wanted`: Indicates that the issue is a good candidate for external contributions and help
-- `good-first-issue`: Marks issues that are suitable for newcomers to the project, often with simpler scope.
-- `community`: Indicates that the issue is related to community engagement, such as events, discussions, or contributions that don't fit into the other categories. From authors who are not contributors to the codebase but are engaging with the project in other ways.
+- `good-first-issue`: Marks issues that are suitable for newcomers to the project, often with simpler scope.

README.md

@@ -1,6 +1,6 @@
 # Agentic DevSecOps
 
-One repo. One GitHub Pages site. Five adoption journeys, four delivery session modules, 59 activities, zero configuration drama.
+One GitHub Pages curriculum with five adoption journeys, four delivery-session modules, and 59 activities.
 
 > **Bring your own.** These activities are built to run on **your** tenant — work each one
 > against your own applications, repositories, and data so the result keeps running in

modules/ghas/resources/README.md

@@ -4,8 +4,9 @@ This directory contains GitHub Advanced Security (GHAS) configuration files that
 to the org-owned Juice Shop repository provisioned in Activity S00 to enable GHAS scanning
 features during the delivery session.
 
-These fixtures are maintained in this repository and are
-now vendored here so that repository can be retired.
+These fixtures were moved here from a retired predecessor repository. Keeping
+them with the curriculum makes the setup reproducible without another source
+repository.
 
 ## Files
 

modules/ghas/setup.md

@@ -9,7 +9,7 @@ These are separate. You run Juice Shop locally for testing; the org repository i
 
 ## GHAS Target Repository
 
-For Activity S00, a participant, team lead, or organizer should create the GHAS target in an org they control. Use the provided setup scripts:
+For Activity S00, a participant, team lead, or organizer should create the GHAS target in an org they control. GHAS reuses the shared GHEC provisioning scripts because they provide the common org setup and safety checks. Use the provided setup scripts:
 
 ```bash
 cd modules/ghec/resources/provisioning/scripts

modules/ghaw/challenges/01-morning-briefing/COACH.md

@@ -12,5 +12,5 @@ This is a concise review overlay. Apply the [Delivery Assurance Standard](../../
 ## Session-specific reviewer focus
 
 - Pitfall 1: Incorrect cron syntax
-- Pitfall 2: No workflowdispatch: for testing
+- Pitfall 2: No `workflow_dispatch` trigger for testing
 - Pitfall 3: Trying to call GitHub API directly instead of using the tool

modules/ghaw/challenges/03-the-watcher/COACH.md

@@ -12,5 +12,5 @@ This is a concise review overlay. Apply the [Delivery Assurance Standard](../../
 ## Session-specific reviewer focus
 
 - Pitfall 1: Path filter is too specific or wrong
-- Pitfall 2: Forgot to include workflowdispatch
+- Pitfall 2: Forgot to include `workflow_dispatch`
 - Pitfall 3: Trying to read commit diff directly instead of using GitHub MCP

modules/ghaw/challenges/07-slash-and-burn/meta.yml

@@ -21,9 +21,9 @@ success_criteria:
   - The workflow runs (visible in Actions tab)
   - A summary comment appears within 30 seconds
   - Summary includes:
-  - Issue title and current state
-  - At least 2 key points from the discussion
-  - Next steps or recommendation
+    - Issue title and current state
+    - At least 2 key points from the discussion
+    - Next steps or recommendation
   - Only authorized users (repo members) can trigger the command
 tags:
   - slash-commands