docs(product-engineering): standardize ADR and as-is conventions

[devantler]

🤖 Generated by the Agentic Engineer

Why

The shared product-engineering contract needs one unambiguous home for ADRs and one documentation perspective across repositories.

What

• Repositories that use ADRs keep every ADR under docs/adr/ and nowhere else.
• Repositories without ADRs are not required to introduce them.
• Documentation, code comments, and resource descriptions state the current behavior, architecture, constraints, and rationale without journey or origin-story narration.

Validation

• git diff --check
• gh skill publish --dry-run

Fixes #77

Summary by CodeRabbit

• Documentation
  • Updated guidance for documenting architecture decisions, including recommended ADR placement under docs/adr/.
  • Clarified that documentation and comments should describe the current state and explain present constraints or rationale.

[Copilot]

Pull request overview

This PR updates the product-engineering skill contract to standardize (1) where ADRs live in repositories that use them and (2) the expected “present-state” documentation voice across repos.

Changes:

• Specify docs/adr/ as the single allowed ADR location for repositories that use ADRs, without requiring ADR adoption where it doesn’t exist.
• Add guidance requiring documentation, code comments, and resource descriptions to describe the current (“as-is”) state rather than narrating migrations or origin stories.

---

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

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5fea43f8-5951-4cb5-a8b2-2c72dc8c8043

📥 Commits

Reviewing files that changed from the base of the PR and between 8b60683 and c702f11.

📒 Files selected for processing (1)

• product-engineering/SKILL.md

---

📝 Walkthrough

Walkthrough

Updates the product-engineering skill with a standard docs/adr/ location for repositories using ADRs and an as-is documentation rule covering current behavior, constraints, comments, and resource descriptions.

Changes

Product engineering guidance

Layer / File(s)	Summary
Documentation contract updates product-engineering/SKILL.md	ADR guidance standardizes docs/adr/ placement without requiring ADR adoption, while documentation guidance requires present-state descriptions and rationale.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related issues

• monorepo issue 2433 — Covers the same ADR location and present-state documentation requirements.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/adr-present-state-docs-77

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}