farhanhidayatulhaq-max/GAMUKIS / .agents/skills/code-readability
code-readability
UnverifiedUse when planning, writing, debugging, reviewing, or refactoring Gamukis code so developers can understand its purpose, trace failures, and continue maintenance without unnecessary confusion.
Code Readability and Maintainability
Use this skill alongside the relevant layer skill and .agents/docs/prd-standard.md §4.3. The goal is code another developer can follow and debug, not a particular line count or style preference.
Before Writing
- Read the active source files and nearby examples before proposing structure or names.
- Identify the responsibility, inputs, outputs, side effects, and failure cases for each planned unit.
- For feature work, ensure the approved PRD blueprint lists all affected files and includes concrete readability acceptance criteria. Follow the repository's PRD gate.
- Prefer existing project conventions when they are clear and fit the requirement.
While Writing
- Choose specific names that reveal intent; avoid unexplained abbreviations and overly generic identifiers.
- Keep each function, component, and module focused. Extract a unit when it has a meaningful responsibility or makes behavior easier to test; avoid needless wrappers and indirection.
- Keep control flow easy to trace. Validate inputs near the boundary, use explicit branches, and make failure paths visible.
- Name domain-significant constants and intermediate values. Do not replace every literal mechanically when a name would add no meaning.
- Keep side effects in the layer responsible for them. Names should not conceal network, database, filesystem, or state changes.
- Explain non-obvious decisions and constraints in comments; avoid comments that merely restate the next line.
- Preserve useful error context without exposing credentials, tokens, or sensitive user data.
- Match the existing folder architecture and neighboring code style. Avoid unrelated cleanup and duplicate implementations.
Debugging and Review
For each changed file, check that a new maintainer can determine:
- What the file and each important unit are responsible for.
- What inputs and outputs are expected, including important contracts.
- Where side effects occur and in what order.
- How invalid input and operational failures are handled.
- Which logs or errors identify the failed operation without leaking sensitive data.
If the behavior is difficult to follow, simplify the structure or improve names before adding explanatory comments. Report unresolved readability issues and record the files reviewed in the task progress or handoff. Do not claim code was reviewed or validated unless that work was actually performed.
Completion Checklist
- Names describe domain intent and important values.
- Functions and components have focused responsibilities.
- Branches, side effects, and error paths are visible.
- Comments explain non-obvious reasons rather than restating code.
- Changed files follow the active architecture and nearby conventions.
- A developer unfamiliar with the change can trace the normal and failure paths.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 107k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 107k | Updated | Claude CodeCodex | Verified | Install |