From b06d6df8058792ecbf6f5e1dcd8756618546c9a8 Mon Sep 17 00:00:00 2001 From: Dina Berry Date: Sat, 14 Mar 2026 09:53:21 -0700 Subject: [PATCH 1/2] docs(pao): add CONTENT DISCIPLINE hard rule to charter Adds a hard rule requiring PAO to search for existing coverage before writing new content, link to canonical pages instead of duplicating, and flag duplication during reviews. Prevents unnecessary docs growth. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/pao/charter.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.squad/agents/pao/charter.md b/.squad/agents/pao/charter.md index aa4d55841..dd59921c6 100644 --- a/.squad/agents/pao/charter.md +++ b/.squad/agents/pao/charter.md @@ -26,6 +26,7 @@ - **DOCS-TEST SYNC (hard rule):** When adding new docs pages (guides, blog posts), update the corresponding test assertions in test/docs-build.test.ts in the SAME commit. Stale test assertions that block CI are a docs team failure. - **CONTRIBUTOR RECOGNITION (hard rule):** Each release includes an update to the Contributors Guide page. No contribution goes unappreciated. - **DOC-IMPACT REVIEW (hard rule):** Review every PR for documentation impact. If a change affects user-facing behavior, ensure corresponding docs are updated or flag the gap. +- **CONTENT DISCIPLINE (hard rule):** Before writing new content, search existing docs for coverage of the same topic. Link to the canonical page instead of duplicating setup steps, config blocks, or explanations. Each concept should live in exactly one place — other pages reference it. When reviewing docs, flag duplication and unnecessary growth. ## Boundaries From c7ac7b63ce7122c3aca8cd0edb962b4b3fe51062 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Sat, 14 Mar 2026 10:20:07 -0700 Subject: [PATCH 2/2] docs(pao): add DEEP LINKING hard rule to charter Require anchor/fragment links when a more specific section exists, rather than linking to just the page URL. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/pao/charter.md | 1 + .squad/agents/pao/history.md | 3 +++ 2 files changed, 4 insertions(+) diff --git a/.squad/agents/pao/charter.md b/.squad/agents/pao/charter.md index dd59921c6..fb387c39d 100644 --- a/.squad/agents/pao/charter.md +++ b/.squad/agents/pao/charter.md @@ -27,6 +27,7 @@ - **CONTRIBUTOR RECOGNITION (hard rule):** Each release includes an update to the Contributors Guide page. No contribution goes unappreciated. - **DOC-IMPACT REVIEW (hard rule):** Review every PR for documentation impact. If a change affects user-facing behavior, ensure corresponding docs are updated or flag the gap. - **CONTENT DISCIPLINE (hard rule):** Before writing new content, search existing docs for coverage of the same topic. Link to the canonical page instead of duplicating setup steps, config blocks, or explanations. Each concept should live in exactly one place — other pages reference it. When reviewing docs, flag duplication and unnecessary growth. +- **DEEP LINKING (hard rule):** When linking between docs pages, use the most specific anchor available (e.g., `guides/mcp/#authentication-errors`) rather than just the page URL. If a heading or section anchor exists for the target content, link to it. ## Boundaries diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md index 48b72105d..4fbc5f6c6 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -47,3 +47,6 @@ Executed boundary review findings from PR #331: (1) Deleted ralph-operations.md ### Cross-Org Authentication Docs (v0.8.26) Created docs/src/content/docs/scenarios/cross-org-auth.md covering GitHub personal + Enterprise Managed Users (EMU) multi-account auth. Three solutions documented: (1) gh auth switch for manual account toggling; (2) Copilot instructions (.github/copilot-instructions.md) for account mapping documentation; (3) Squad skill pattern for auth error detection and recovery. Covered git credential helpers (per-host and per-org), EMU hostname variations (github.com vs dedicated instances), and common error messages (HTTP 401, authentication required). Added cross-references in troubleshooting.md (new section), enterprise-platforms.md (authentication section), and navigation.ts. Updated test/docs-build.test.ts with 'cross-org-auth' in EXPECTED_SCENARIOS. Pattern: Microsoft Style Guide (sentence-case), "Try this" prompts at top, problem/solution structure, practical examples over abstractions, links to related pages at bottom. +### Teams MCP Documentation Audit (v0.8.26) +Audited Teams MCP integration documentation per #258. Key findings: (1) All path references used placeholder `path/to/*.js` without clarifying these require actual MCP server implementations; (2) Link to `microsoft/IF-MCP-Server-for-Microsoft-Teams` was misleading — that repo is actually a Court Listener demo, not a general Teams server; (3) No example code exists in Squad codebase; (4) Community member benleane83 published working reference implementation at https://gist.github.com/benleane83/f37b5bc1ed3d00e320ba48886109b82a. Fixes applied: replaced placeholder paths with `/absolute/path/to/*.js` format, removed broken Microsoft Teams MCP reference, added link to community gist, clarified users must download/create MCP servers, updated all MCP config examples in notifications.md, mcp.md, and portability.md. Pattern reinforced: external tool integrations require explicit "where to get it" guidance, not assumptions about bundled code. +