[Feedback]: Portfolio practice reuse produced a retrieval-aware planning convention

[sergeliatko]

Observation

During a founding-maintainer operational run with coordinate-github-repositories v1.11.0, the agent used an authorized private portfolio inventory to locate explicit planning and artifact-naming practices across a large set of read-only repository workspaces. It read only relevant safe documentation, followed source instructions, deduplicated shared convention copies by content hash, distinguished current authority from historical examples, and compared several approaches before adapting them into the single authorized implementation repository.

The user questioned whether task-package filenames needed to repeat the package name. The agent tested the actual IDE and terminal retrieval surfaces, confirmed that both preserved full relative paths, and changed the recommendation accordingly: semantic parent directories carry package context, while fixed local role filenames avoid redundancy. Package qualification is reserved for a proven consumer that discards parent paths.

The same run reviewed an existing portfolio control-plane plan as planning input rather than authority. It retained the coordination boundary but moved manual pilots ahead of canonical schemas and generalized automation, documented sources of truth and owner checkpoints, and kept all evidence repositories unchanged.

Intended Outcome

Reuse the strongest planning and naming practices already present in an authorized portfolio to improve one registry without adding a competing planning tree, copying historical architecture, or imposing a generic convention.

Impact or Usefulness

The result was a documented planning hierarchy, an accepted retrieval-aware artifact convention, and an evidence-gated operating plan. It avoided bulk renames, duplicate sources of truth, premature schema design, and unauthorized writes across the portfolio. The repository's complete validation remained green.

Expected or Preferred Behavior

This outcome validates the existing Portfolio Practice Reuse behavior and suggests a representative information-architecture variant. A fixture could verify that the agent uses an authorized inventory to find analogous practices, checks source authority and duplicate copies, tests the actual retrieval consumer before choosing filename redundancy, treats a proposed plan as revisable input, implements only in the active workspace, and preserves provenance without exposing private topology.

Sanitized Context

This was first-party operational evidence from the skill's founding maintainer, not independent adoption evidence. The agent had read-only access to authorized evidence repositories, write access to one active registry, local Git and shell search, an IDE search surface, and GitHub CLI and app access. Private repository names, account relationships, local paths, and raw logs are omitted.

Evidence, Uncertainty, or Possible Explanation

Observed: the active repository recorded the result in a substantial coordination commit, followed by a separate one-file security-hardening commit before private publication. The literal latest commit only expanded ignored sensitive-file patterns based on repository safety rules; the planning and naming outcome belongs to the preceding commit.

Hypothesis: the current guidance is sufficient to produce this behavior, but a fixture covering information architecture and retrieval-surface verification would make the behavior easier to preserve beyond the existing release-process example.

Related Links

• Portfolio Practice Reuse behavior fixture
• Issue #23: workspace, authority, documentation, and placement boundaries
• Issue #27: functionality and knowledge benefit relationships

[sergeliatko]

Two corrections for the record, then direction for maintenance.

First, attribution. The retrieval-surface test (IDE and terminal path handling) was my request, not the agent's initiative. The agent ran it properly and changed its recommendation based on the result instead of defending the previous one, which is worth something, but it did not think to test on its own. What was the agent's own: deduplicating convention copies by content hash, separating currently authoritative copies from historical examples, and demoting the existing control-plane plan to revisable input with resequencing (pilots before schemas). The record should stay precise about who initiated what.

Second, the write-up above puts too much weight on the filename redundancy question. That was a detail. The valuable outcome of this run is different: at this portfolio scale you cannot organize content without a clear file naming convention, and the run produced one, derived from our own strongest existing practices instead of some generic standard, and verified against the surfaces that actually retrieve the files. Naming is retrieval infrastructure. For agents even more than for humans: an agent finds things by paths and names, it has no memory of where I put things. A consistent convention is what makes a portfolio of this size agent-legible. Ad hoc naming that a human survives by memory is a wall for an agent.

For maintenance, three things:

1. The fixture should assert the full arc, and one step beyond what was observed: given an authorized portfolio at scale with ad hoc naming, the agent recognizes that a convention is warranted, derives it from currently authoritative practices, verifies it against the real consuming surfaces without being asked, and documents it as a single source of truth in the active workspace. No bulk renames. The convention applies forward.

2. A small runtime addition near the findability guidance, a few lines only: at portfolio scale, artifact naming and placement conventions are coordination infrastructure; when evidence shows ad hoc naming, deriving a convention from the portfolio's own proven practices is a legitimate recommendation; any proposed convention gets checked against the actual consuming surfaces (IDE search, terminal, CI, registry, human reader) before adoption. The empirical check only happened here because I asked for it, which is exactly the argument for codifying it: the fixture preserves the behavior, the reference line makes it the default instead of something the user has to think to request.

3. One rule for feedback-and-improvement: every operational record that validates or extends a behavior either maps to an existing fixture or proposes a new one. This issue did it by instinct. Make it a rule.

Keep the runtime addition minimal. The fixture carries the weight.

[sergeliatko]

/agent-execute review this issue plan and release it as a next minor version, also check if we should have some sort of a folder to organize the feedback artifacts so that they become accessible through the repository entry points.

[sergeliatko]

Implemented in #49 and published in v1.12.0.

The release adds a focused findability and convention workflow that:

• tests relevant human, agent, and tool consumers when authorized capabilities are available;
• presents every new or revised convention to an authorized human before adoption;
• separates convention acceptance from exact write authority;
• treats local success as evidence for a separately reviewed portfolio proposal;
• supports scalable approval through an explicit target list or stable reviewed snapshot with per-target revalidation;
• preserves no change, forward adoption, legacy compatibility, local instructions, private topology, owner-maintained sources of truth, and the automation design gate.

Architecture Decision 0007 records the durable design. The evaluation registry now contains 75 cases across 18 segments, including seven findability cases. Four fresh-agent forward reviews passed after one pre-proposal local-instruction ambiguity was repaired and rechecked.

GitHub Issues remain the feedback and task surface. The README and feedback guide now link the canonical feedback label view, and accepted operational runtime evidence must map to an existing or proposed fixture without adding reporter burden. No separate feedback-artifact directory was added.

The exact release assets, checksums, attestations, public installation, and update from v1.11.0 all passed. What remains unknown is how the convention workflow performs across representative real portfolios and consumers; that evidence should trigger future review if exceptions, maintenance burden, or consumer conflicts dominate.

[sergeliatko]

Follow-up observation from v1.12.0

During a later operational run, a user asked an agent to create a durable feature-planning package for a direct external API connector. The user questioned the initial proposal to repeat the feature slug in both the package directory and local filenames.

The agent applied the released findability workflow to an authorized read-only portfolio inventory. It compared currently authoritative planning and naming practices, confirmed that the relevant IDE and terminal consumers preserve full relative paths, and adapted the strongest compatible practices only in the active implementation repository.

The resulting local convention uses docs/plans/<feature>/README.md as the human entrypoint and progress.yaml as the machine status and dependency authority. It is documented in one repository-owned convention and linked from the root agent instructions. Historical artifacts were not renamed.

The run also reused a compatible validation mechanism from another portfolio practice: JSON Schema draft-07, local PhpStorm and YAML Language Server schema directives, and an AJV plus YAML repository check. The agent did not copy the source feature's domain schema. It created a planning-specific contract and added semantic checks for missing references, dependency ordering, cycles, lifecycle reconciliation, and human checkpoints.

Impact or Usefulness

This provides follow-up evidence that the v1.12.0 convention workflow can move from portfolio discovery to a clean repository-local planning contract without creating hidden authority, copying unrelated semantics, or mutating evidence repositories. The complete repository verification passed.

Suggested Maintainer Use

This evidence maps to the existing Portfolio Practice Reuse and findability fixtures. A future fixture refinement could verify that an agent distinguishes a reusable mechanism from its source domain contract, documents the adapted convention in the active repository's normal instruction surface, and validates it through both IDE and automated consumers.

Sanitized Context

This was an operational observation with one writable implementation repository and several authorized read-only evidence repositories. Private repository identities, account relationships, local paths, credentials, and raw logs are omitted.