docs: reorganize playbook navigation into role-based sections

[vdstrizhkova]

Pull Request Template

What are you trying to address

This is part 2 of 3 splitting PR #1130. It is purely a reorganization of the playbook's information architecture - it adds no new guidance content (the AI/HVE additions live in #1133).

Scope: 12 files changed (+249 / -82) relative to its base.

Reorganization

• New "Start Here" section with role-based on-ramps: docs/start-here/README.md, for-engineers.md, for-data-scientists.md, for-leads.md, project-kickoff-checklist.md, and .pages.
• New Non-Functional Requirements section (docs/non-functional-requirements/README.md) consolidating NFR content into its own area.
• Navigation updates across docs/.pages, README.md, and docs/README.md.
• Renamed docs/design/readme.md -> docs/design/README.md for consistency.
• Removed docs/the-first-week-of-an-ise-project.md (superseded by the Start Here section).

Stacking: this branch is stacked on #1133. Until #1133 merges, this PR's diff also shows those changes; it reduces to reorganization-only once #1133 lands (or after a rebase onto main).

Breaking change: the first-week page was removed; external links to the old path should redirect to the Start Here section.

Checklist

READY TO PR? Use the check-list below to ensure your branch is ready for PR.

• Changes follow the repo structure and land in the appropriate folder and section
• No confidential information
• No duplicated content
• Labeled appropriately
• This PR was reviewed by at least one subject matter expert
• No lint check errors related to your changes

[Shiran Rubin (shiranr)]

The description states this PR is "purely a reorganization… adds no new guidance content." Because it's stacked on #1133, the diff actually includes ~700 lines of new AI/HVE content across docs/CI-CD/, docs/UI-UX/, docs/ai-assisted-engineering/README.md (139 new lines), docs/ml-and-ai-projects/generative-ai-and-agentic-systems.md (89 new lines), docs/non-functional-requirements/privacy/, docs/observability/, docs/security/threat-modelling.md, docs/developer-experience/copilots.md, and more. The author correctly flags this in the stacking note, but the practical effect is that the PR can't be reviewed as reorg-only until #1133 lands or the branch is rebased. Please rebase and re-request review, or update the description to be explicit about what's actually here.

[Copilot]

Pull request overview

This PR updates the playbook’s information architecture to introduce role-based entry points (“Start Here”), reorganize navigation, and consolidate non-functional requirements—while also including (per the PR’s stacking note) additional AI-assisted engineering guidance changes that will reduce after rebasing.

Changes:

• Add a new docs/start-here/ section (persona on-ramps + kickoff checklist) and remove the legacy “first week” page.
• Introduce / expand AI-assisted engineering guidance across multiple sections (security, testing, observability, documentation, etc.).
• Update MkDocs navigation and supporting repo config (workflow action bumps, lint config note, docs requirements pin, dictionaries).

Reviewed changes

Copilot reviewed 60 out of 63 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
requirements-docs.txt	Pin pygments for docs build toolchain stability.
README.md	Update top-level links to new Start Here / kickoff checklist and Design README.
docs/UI-UX/recommended-technologies.md	Markdown formatting cleanup and FAST link update.
docs/UI-UX/README.md	Add AI-assisted UI/UX guidance and formatting fixes.
docs/the-first-week-of-an-ise-project.md	Remove legacy kickoff/first-week page (superseded).
docs/start-here/README.md	New Start Here landing page.
docs/start-here/project-kickoff-checklist.md	New sprint-sequenced kickoff checklist.
docs/start-here/for-leads.md	New curated reading path for leads/PMs.
docs/start-here/for-engineers.md	New curated reading path for engineers.
docs/start-here/for-data-scientists.md	New curated reading path for data scientists/ML engineers.
docs/start-here/.pages	Nav config for Start Here section.
docs/source-control/secrets-management.md	Add AI prompt/logs as potential secret sources guidance.
docs/source-control/README.md	Add AI-assisted branch/review/traceability guidance.
docs/source-control/naming-branches.md	Add agent-authored branch naming guidance.
docs/source-control/git-guidance/README.md	Add AI-assisted change traceability section.
docs/security/threat-modelling.md	Add AI systems threat modeling considerations.
docs/security/README.md	Add AI/agent security section and references.
docs/README.md	Point newcomers to Start Here; update kickoff checklist link.
docs/observability/recipes-observability.md	Minor link text formatting fix.
docs/observability/README.md	Add AI observability overview guidance.
docs/observability/pillars/tracing.md	Clarify OpenTelemetry guidance wording.
docs/observability/ml-observability.md	Add LLM/RAG/agent telemetry guidance.
docs/observability/microservices.md	Clarify OpenTelemetry propagation wording.
docs/observability/logs-privacy.md	Add AI-specific logging/privacy guidance.
docs/observability/correlation-id.md	Clarify OpenTelemetry correlation guidance.
docs/observability/best-practices.md	Add AI-specific observability best practices.
docs/non-functional-requirements/README.md	New NFR landing page with quality attribute index.
docs/non-functional-requirements/privacy/README.md	Add AI privacy review prompts.
docs/non-functional-requirements/privacy/data-handling.md	Add AI tool data handling guidance.
docs/non-functional-requirements/maintainability.md	Link maintainability to testing fundamentals taxonomy.
docs/non-functional-requirements/accessibility.md	Add AI experiences + AI-assisted accessibility guidance.
docs/ml-and-ai-projects/responsible-ai.md	Add gen-AI/agent Responsible AI review prompts.
docs/ml-and-ai-projects/README.md	Add AI-enabled project entry points and links.
docs/ml-and-ai-projects/model-experimentation.md	Add gen-AI/agent evaluation guidance.
docs/ml-and-ai-projects/generative-ai-and-agentic-systems.md	New guide for gen-AI/agentic system engineering.
docs/engineering-fundamentals-checklist.md	Add AI-assisted engineering checklist section.
docs/engineering-feedback/README.md	Add AI tooling feedback guidance.
docs/documentation/README.md	Add AI-assisted documentation guidance.
docs/documentation/guidance/code.md	Add guidance about generated comments/explanations.
docs/documentation/best-practices/automation.md	Add guidance preferring automation over generated prose.
docs/developer-experience/README.md	Add AI-assisted DevEx guidance.
docs/developer-experience/copilots.md	Expand Copilots guidance with team operating model sections.
docs/design/README.md	Add AI-assisted / AI-enabled systems design guidance.
docs/design/design-reviews/recipes/high-level-design-recipe.md	Add AI-specific prompts for design review artifacts.
docs/design/design-patterns/non-functional-requirements-capture-guide.md	Add AI/agent measurable NFR table and fix privacy link.
docs/code-reviews/README.md	Add “reviewing AI-assisted changes” section.
docs/code-reviews/pull-request-template.md	Add PR checklist item for AI assistance disclosure.
docs/code-reviews/process-guidance/reviewer-guidance.md	Add AI-assisted/agent-authored review guidance section.
docs/CI-CD/README.md	Add AI release-artifact validation guidance in CI/CD.
docs/CI-CD/continuous-integration.md	Add AI artifact expectations + link updates and clarifications.
docs/automated-testing/unit-testing/README.md	Markdown whitespace cleanup.
docs/automated-testing/test-planning.md	Add AI evaluation planning section.
docs/automated-testing/README.md	Add testing guidance for AI-assisted/AI-enabled changes.
docs/ai-assisted-engineering/README.md	New AI-Assisted Engineering baseline guide.
docs/agile-development/team-agreements/definition-of-done.md	Reference automated testing fundamentals taxonomy.
docs/agile-development/README.md	Link Agile guidance to AI-assisted engineering baseline.
docs/agile-development/branching-and-cicd.md	Clarify ownership of canonical branching / PR policies.
docs/.pages	Update top-level docs nav to include Start Here, NFR, AI sections.
.mega-linter.yml	Add rationale comment for keeping lychee disabled.
.gitignore	Ignore Copilot agent tracking artifacts directory.
.github/workflows/mkdocs.yml	Bump actions versions used by docs workflow.
.gitattributes	Mark workflow lock files as generated and merge=ours.
.cspell.json	Add new terms to spellchecker dictionary.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Shiran Rubin (shiranr)]

project-kickoff-checklist.md links to ../agile-development/README.md#ai-tooling-considerations — the change to agile-development/README.md in this PR adds a paragraph but no ## AI tooling considerations heading.

[vdstrizhkova]

is this an issue?