skills.rest
Cynthia1070711
Cynthia1070711COMMUNITY
Explore all skills by this author →
WebsiteGitHub

phycool-intentional-decisions

Manages intentional decision debt through four-layer code, ADR, database, and memory annotations.

10|3|Updated Mar 7, 2026
Search Tags:#code review#adr#technical debt#sqlite#decision tracking#code annotation#intentional decision debt
One-click install
npx skills add https://github.com/Cynthia1070711/PHYCOOL_Tools --skill phycool-intentional-decisions-cynthia1070711
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: phycool-intentional-decisions
Source: https://github.com/Cynthia1070711/PHYCOOL_Tools/tree/main/config-templates/claude/skills/phycool-intentional-decisions
Command: npx skills add https://github.com/Cynthia1070711/PHYCOOL_Tools --skill phycool-intentional-decisions-cynthia1070711

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Teams often confuse business-driven "deliberately not fixed" behaviors with ordinary technical debt, causing developers to accidentally "fix" intentional product decisions. This Skill provides a dedicated Intentional Decision Debt (IDD) system that keeps such decisions discoverable and protected across code, ADRs, database records, and memory files. ## Core Features & Use Cases - Four-Layer Annotation System: Every IDD is recorded in code comments ([Intentional: IDD-XXX]), an ADR document, a SQLite intentional_decisions table with FTS5 search, and memory files for critical items. - Four Sub-Types with Lifecycle Management: Classifies decisions as Commercial, Strategic, Regulatory, or User-driven, with event-triggered re-evaluation, supersession, and retirement workflows (never hard deletion). - Workflow Gates and Tooling: Integrates MCP tools, CLI scripts, pre-edit awareness checks in dev-story, code-review detection gates, and prompt-injection hooks so IDDs surface before edits violate forbidden changes. - Use Case: A developer about to add a free-plan gating check to an editor panel is warned that IDD-COM-001 forbids it, because the open editor is a deliberate conversion-funnel decision documented in ADR-IDD-COM-001. ## Quick Start Ask the assistant to search intentional decisions for the file you plan to edit and confirm none of the forbidden changes apply before modifying the code.

Frequently Asked Questions about phycool-intentional-decisions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is intentional decision debt and how is it different from technical debt?▼

Intentional decision debt (IDD) records behavior deliberately kept unchanged due to business, strategy, regulatory, or user decisions, while technical debt is work postponed due to time or oversight. The two are mutually exclusive and stored in separate database tables.

How do I annotate an intentional decision in source code?▼

Add an inline comment like `// [Intentional: IDD-COM-001]` with a reason and a reference to the ADR file. Block-style annotations with fields such as decision-by, re-evaluate-trigger, and forbidden-changes are recommended for critical decisions, with formats for TypeScript, C#, Python, SQL, and Markdown.

What are the four layers of the IDD annotation system?▼

Layer 1 is code inline annotation, Layer 2 is an ADR document under docs/technical-decisions, Layer 3 is the intentional_decisions database table with FTS5 search, and Layer 4 is memory files plus MEMORY.md entries for critical items only.

Can an intentional decision be deleted once it is no longer valid?▼

No, direct deletion is forbidden. Decisions must be retired or superseded by a newer IDD, preserving historical traceability, and code annotations and ADR titles are updated to reflect the retired or superseded status.

How does the skill prevent developers from violating forbidden changes?▼

A pre-edit awareness gate in the dev-story workflow queries active IDDs for files being modified and warns about forbidden changes, while code-review detection gates and stop-hook annotation verification catch violations retrospectively.

When should I create an IDD instead of marking an issue as won't fix?▼

Create an IDD whenever the reason for not fixing is driven by business, strategy, regulation, or user decisions, confirmed through the Q1-Q4 detection questions. WON'T FIX is reserved for rare pure-style cases with zero practical risk.

Related Skills

Explore More Software Engineering Skills→
maxenergymaxenergy

improve-codebase-architecture

Identify deepening opportunities in codebases using ADRs and CONTEXT.md vocabulary.

Community
Advanced
putrawitamaputrawitama
1

freeze

Restrict file edits to a single directory while allowing read access.

Community
Intermediate
whmathews15whmathews15
1

tech-debt

Review technical debt mentions and generate a prioritized inventory with impact and effort classifications.

Community
Intermediate
cescraflicescrafli

architecture-decision-records

Capture architectural decisions as structured ADR documents with context and alternatives.

Community
Advanced