Refresh engineering principles with the outcome-scope principle

[itsHabib]

Summary

Refreshes this repository's managed eng-philo block from itsHabib/cc-skills#72, which adds principle 7:

Build only what the outcome requires. Start from the intended outcome. For each option, abstraction, dependency, or workflow step, ask what requires it, what concretely breaks without it, and whether a simpler alternative is adequate. Prefer existing capabilities and direct implementations; derive information already known. Consider setup, operation, and maintenance, not just line count. Preserve required behavior, correctness, security, accessibility, and authority boundaries. "Nothing worth cutting" is a valid result.

This is judgment guidance only. It adds no check, score, checklist, reviewer, or gate, and it does not require running /cut.

What this changes

• Only the lines between the eng-philo markers in CLAUDE.md and AGENTS.md. Everything outside the block is byte-identical to main at 10b066c.
• An earlier eng-philo version stamped this block, so principles 1–6 and the Go section also move to the current canonical wording. The old block held no repository-specific content.
• Markdown only: no code, configuration, or workflow changes.

Validation

• Rendered with the updated plan-block.sh. A second plan against this branch is empty, so the refresh is idempotent.
• The CLAUDE.md and AGENTS.md blocks are byte-identical, and principle 7 matches the global Claude and Codex guidance word for word.
• The diff is Markdown only, so the code checks are left to CI.

Land after itsHabib/cc-skills#72 so this repository never carries wording ahead of its renderer.

🤖 Generated with Claude Code

[itsHabib]

@codex review

[itsHabib]

@claude review

[claude]

Claude finished @itsHabib's task in 1m 27s —— View job

---

PR Review — docs/eng-philo-outcome-scope

Reviewed head commit 11f38ca / af8ab9f (CLAUDE.md / AGENTS.md).

• Gather context from PR description and changed files
• Read current state of CLAUDE.md and AGENTS.md
• Diff the changes against origin/main
• Post review feedback

---

Summary

This is a Markdown-only managed-block refresh. The diff is byte-identical across CLAUDE.md and AGENTS.md, no code is touched, and principle 7 matches the PR description word-for-word. The structural claims in the PR body all check out.

Observations

New principle 7 (CLAUDE.md:119 / AGENTS.md:119) — the addition is the point of the PR. The wording is clear, self-contained, and the closing line ("Nothing worth cutting is a valid result") is a useful termination condition that guards against over-application. No issues.

Rewording of principles 1–6 — generally tighter. Two specific details are worth noting as intentional upstream decisions:

• Principle 2 lost the per-scope clarification: "The budget is per-scope, not per-function — a closure / anon fn is its own scope, so a for+if inside a closure is fine." That was the most non-obvious part of the rule. The new wording ("A loop plus a condition is the ceiling") is correct but could be misread as a per-function limit. Since this tracks cc-skills#72 verbatim, it's an upstream call — worth flagging there if it causes confusion in practice.

• Principle 5 dropped "Make the zero value useful." That's a core Go idiom; its absence is noticeable. Again, upstream decision.

Go idioms section — "small consumer-owned interfaces" is a valuable clarification over the old "small interfaces (1–2 methods)". Consumer-owned is the point that matters most in Go interface design. Good addition.

Enforcement line — explicitly naming gofmt and go vet alongside golangci-lint is a net improvement; they were in the ## Checks section but not in the eng-philo block, so an agent reading only the block would have missed them.

Practical Go link — the intro dropped the hyperlink to Dave Cheney's Practical Go. Upstream decision. Minor loss of traceability for the principles' lineage.

Marker comment — — → - (em-dash to hyphen) is intentional template normalization, not a mistake.

Verdict

LGTM. The PR does exactly what it says: refreshes the managed block from cc-skills#72, adds principle 7, and touches nothing else. The two dropped details (per-scope nesting nuance, zero-value-useful) are upstream decisions tracked faithfully here. No blocking issues.

Land after cc-skills#72 as noted.

---

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-13T15:22:06.996696Z	0ab5661	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 0ab56613bb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Reviewer: claude
Reviewed commit: 0ab56613bb545e541a60f4bf2e2cee7211de7fb8

[itsHabib]

Disposition for the review above. No code change on this PR.

• P2 closure note, P5 "make the zero value useful", Practical Go link: these were dropped when the canonical renderer shortened its wording in itsHabib/cc-skills#24. This refresh only converges on that render. Bringing them back belongs in the renderer, where every repository gets them. They are tracked as a follow-up rather than hand-edited inside a managed block.
• Landing order: after itsHabib/cc-skills#72.