Update audit-docs skill/prompt for two audiences

[AlexJSully]

Update audit-docs skill/prompt for two audiences: newcomer and experience dev within the codebase.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
portfolio	Ready	Preview	Sep 2, 2026 12:17am UTC

[Copilot]

🟡 Changes recommended

next.config.js introduces an agentRules key that is not consumed anywhere in the repo and is likely an invalid Next.js config option, so it should be removed or implemented to avoid confusion/warnings.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR primarily updates the audit-docs prompt/skill to explicitly enforce writing documentation that serves two audiences (a newcomer and an experienced contributor), and propagates that guidance into related docs-authoring instructions and audit templates. It also includes dependency upgrades (Next.js, Cypress, concurrently) plus an added next.config.js flag.

Changes:

• Expand audit-docs guidance to require orientation-first documentation that still provides full depth for experienced readers, including updated reporting formats and reference material.
• Sync the “two readers” guidance into Copilot/Claude documentation-authoring rules and prompt readmes.
• Upgrade Next.js/Cypress/concurrently and refresh package-lock.json, plus add a next.config.js config key.

File summaries

File	Description
package.json	Bumps next, cypress, and concurrently versions.
package-lock.json	Lockfile refresh reflecting dependency upgrades and transitive changes.
next.config.js	Adds agentRules: false to Next.js config object.
.github/prompts/readme.md	Updates audit-docs description to explicitly mention the two-audience requirement.
.github/prompts/audit-docs.prompt.md	Updates the prompt content to enforce newcomer-first orientation and explicit term introduction.
.github/copilot-instructions.md	Adds “two readers” and “introduce terms of art” bullets to the always-apply doc subset.
.claude/skills/audit-docs/SKILL.md	Mirrors prompt updates and adds a new reference doc for writing to both audiences.
.claude/skills/audit-docs/references/writing-for-both-readers.md	New detailed guidance with examples and a “read-it-cold” procedure.
.claude/skills/audit-docs/references/voice-and-ai-tells.md	Adjusts examples to preserve orientation while removing “document signposting” tells.
.claude/skills/audit-docs/references/evidence-and-citation.md	Clarifies that the “no pasted source” rule is about evidence, not copyable usage examples.
.claude/skills/audit-docs/assets/audit-report.template.md	Extends reporting to include newcomer/experienced-reader outcomes per document and entry-path status.
.claude/skills/audit-docs/agents/curation-reviewer.md	Renames the two reader personas and aligns the procedure/output format with the new framing.
.claude/skills/audit-docs/agents/coverage-mapper.md	Adds a Diátaxis “type” column plus entry-path reporting and type counts.
.claude/skills/audit-docs/agents/claim-verifier.md	Clarifies multi-file/orientation claim verification expectations.
.claude/rules/docs-authoring.md	Adds the “two readers” rule and term-of-art introduction guidance for markdown edits.

Review details

• Files reviewed: 13/15 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.