redhat-developer / redhat-developer/rhdh-plugins

Add naming fidelity guidance to repo-local code agent definition

Open Beginner friendly
#4,335 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature ready-for-triage triaged
Dominant language
TypeScript
Stars
48
Forks
120
Avg merge
2d 6h
Merged PRs (30d)
337

Description

What happened

On PR #4258, issue #4256 explicitly stated: "Add a new module called catalog" and referenced CatalogMetricProvider as the class name. The code agent (run 31537419298) instead named the module scorecard-backend-module-catalog-metadata, the class CatalogMetadataMetricProvider, and the config key catalogMetadata. The human then requested renaming in fix iteration 5 (renamed folder, classes, IDs — 5 items in a single /fs-fix). The cancelled fix iteration 4 was also related to the same naming mismatch (the human started with example files before deciding to rename everything). This naming deviation caused ~35 minutes of fix agent compute time and required the human to write detailed rename instructions.

What could go better

The code agent definition says "Keep changes minimal. Every line in your diff must be justified by the issue." This should imply naming fidelity, but the agent interpreted the module's purpose (checking metadata attributes) and added the "metadata" qualifier. The issue was explicit about the name — it used backtick-formatted catalog — but the code agent prioritized descriptive naming over specification compliance.

Confidence is moderate. This could be a one-off judgment call, or it could reflect a systematic tendency for code agents to add qualifiers that "improve" names beyond what the issue specifies. The existing "keep changes minimal" constraint is too abstract to catch this — it focuses on code scope, not naming fidelity. A more explicit instruction about preserving issue-specified names would make the expectation concrete.

Uncertainty: the code agent may have been influenced by the issue body mentioning "catalog entity metadata attributes" and reasonably derived a more descriptive name. But when a name is explicitly specified, specification compliance should win over descriptiveness.

Proposed change

Add a naming fidelity clause to the Constraints section of .fullsend/rhdh/agents/code.md:

- When the issue specifies a name for a module, package, class, function, or
  config key (especially in backtick-formatted code spans), use that exact
  name. Do not add qualifiers, prefixes, or suffixes the issue did not
  authorize. If you believe the specified name is misleading or technically
  problematic, note the concern in your commit message but use the specified
  name — the reviewer or human can decide whether to rename.

This clause makes the implicit naming expectation in "keep changes minimal" concrete and specific to naming decisions.

Validation criteria

The next 3 code agent runs on this repo where the issue specifies an explicit name (in backticks or quoted) for a module, class, or config key should use that exact name without modification. If the code agent does add a qualifier, it should document why in the commit message. Verify by comparing the issue-specified name with the code agent's chosen name in the initial PR commit.


Generated by retro agent from https://github.com/redhat-developer/rhdh-plugins/pull/4258

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Update the Constraints section of .fullsend/rhdh/agents/code.md with the proposed naming-fidelity guidance. Review the existing “Keep changes minimal” constraint first, then confirm the new clause preserves explicitly specified names; validation compares names in the next three applicable code-agent runs with the issue text.

Written by the indexing model from the issue text.

Assessment

Domain
developer-experience, tooling
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
86/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.